go_proto_library 生成的 .pb.go 文件为什么总找不到包？
根本原因是 protoc 生成代码时默认用 package 声明匹配 .proto 文件的 package，但 Go 的 import 路径和磁盘路径必须一致，而很多人把 .proto 放在 api/ 下却希望生成到 github.com/x/y/api，结果 Go 编译器只认路径，不认 package 声明。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 用
--go_out=paths=source_relative:./让protoc按.proto相对路径生成文件（比如api/v1/user.proto→ 生成api/v1/user.pb.go） - 确保
.proto文件顶部的option go_package = "github.com/x/y/api/v1";和你最终import的路径完全一致（包括末尾斜杠或版本号） - 别依赖
go_package自动推导：Bazel 的go_proto_library或buf都会严格检查该字段，缺值或格式错（如漏双引号、含空格）直接报错go_package option must be specified
用 buf 替代裸 protoc 时怎么控制输出路径？
buf 默认不生成文件，只校验；要生成得配 buf.gen.yaml，且路径映射逻辑和 protoc 不同——它按 go_package 的值决定写入位置，不是按 .proto 路径。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
-
buf.gen.yaml中必须显式启用plugin: buf.build/protocolbuffers/go，并设out: ./（注意是根目录，不是gen/） -
go_package必须带模块前缀，例如"github.com/x/y/api/v1;v1"，分号后是本地包名（import时用的别名），前面是模块路径（决定生成到哪） - 常见坑：
go_package = "api/v1"这种相对路径在buf下会生成到./api/v1/，但 Go module 要求 import 路径为完整模块路径，导致编译失败
多个 .proto 引用同一 proto 文件，生成后出现 import cycle not allowed
这不是循环 import，而是多个 .pb.go 文件都试图 import "google/protobuf/timestamp.pb.go" 这类标准类型，但 Go 把它们当不同包处理（因生成路径不同），结果编译器认为 A 依赖 B，B 又依赖 A。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 所有项目统一用
google.golang.org/protobuf（非旧版github.com/golang/protobuf），并在go.mod中 replace 掉旧包 - 用
protoc --go_opt=module=github.com/x/y（或buf.gen.yaml中设module）让所有生成代码共享同一模块路径，避免标准类型被重复生成 - 删掉手动生成的
google/protobuf/目录——这些应由go get google.golang.org/protobuf/types/known/timestamppb提供，不该自己生成
Go module 路径和 go_package 不一致时，IDE 为什么标红但 go build 却能过？
因为 go build 只看磁盘路径和 go.mod 里声明的 module 名，而 VS Code 的 gopls 会读 go_package 字段做符号解析。两者不一致时，gopls 找不到定义，但编译器按实际路径走，所以能过。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 运行
go list -m确认当前 module 名，然后确保每个.proto的go_package以该 module 名开头（如module github.com/x/y→go_package = "github.com/x/y/api/v1"） - 用
buf check breaking配合buf.yaml中的build.roots显式声明 proto 根目录，避免 gopls 因找不到buf.yaml而退化为路径猜测 - 别在
go_package里写../或变量（如$MODULE）——这些在生成时不会展开，gopls 会直接当字面量解析
最常被忽略的是 go_package 分号后的本地包名：它不影响 import 路径，但影响生成文件里的 package 声明，如果多个 proto 设了相同本地名又不在同一目录，Go 会报 duplicate package declaration，而且这个错误不提示具体哪个文件冲突。
