Go语言用Protocol Buffers的关键在编译、路径、序列化三关：protoc-gen-go需显式指定路径或确保在$PATH；import路径错误应通过--go_opt=module统一配置；JSON字段映射失败须用protojson.UnmarshalOptions并设UseProtoNames: false。
Go 语言用 Protocol Buffers 不是“写完 .proto 就能跑”，真正卡住人的永远是编译、路径、序列化这三关。版本不匹配、protoc 参数顺序错、proto.Marshal panic、JSON 字段名对不上——这些不是配置问题，是工具链行为没被理解透。
protoc --go_out 报 “plugin not found” 怎么办
这不是插件没装，而是 protoc 根本没找到 protoc-gen-go 可执行文件。它不查 $GOPATH/bin，也不自动走 $PATH，除非你显式告诉它。
- 先确认已安装：运行
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest（注意不是旧版github.com/golang/protobuf） - 检查二进制是否存在：
which protoc-gen-go；若为空，说明没进$PATH，需补上$(go env GOPATH)/bin - 最稳妥方式：在
protoc命令中显式指定插件路径，例如：protoc --plugin=protoc-gen-go=$(which protoc-gen-go) --go_out=. --go_opt=paths=source_relative example.proto -
--go_out=.末尾的.前必须有=，且不能漏掉冒号分隔逻辑（v3.21+ 后部分场景已弱化，但老项目仍敏感）
生成的 .pb.go 文件 import 路径错了
常见现象是 go build 报 no required module provides package google.golang.org/protobuf/proto，或找不到自定义包路径。根源在于 go_package 配置和 --go_opt=module 没对齐。
-
option go_package = "github.com/yourname/project/pb"必须与你go mod init的模块名前缀一致（比如go mod init github.com/yourname/project） - 不要手改生成文件里的
import行——所有路径修正都应通过--go_opt=module=github.com/yourname/project控制 - 如果
.proto放在pb/子目录下，又希望生成代码也在pb/包内，必须加--go_opt=paths=source_relative，否则可能生成到pb/pb/xxx.pb.go - 确保已
go get google.golang.org/protobuf@latest，且go.sum中有对应 checksum
proto.Marshal panic: “nil pointer to struct”
不是数据为空，而是结构体里某个 *T 类型字段（尤其是嵌套 message）为 nil。Protobuf v2 默认拒绝任何未初始化的指针字段。
立即学习“go语言免费学习笔记（深入）”；
- 别用
new(YourMsg)后直接赋值——它只分配顶层内存，子字段仍是nil - 推荐写法：
msg := &YourMsg{Child: &ChildMsg{}}，确保所有*T字段非 nil - 若从 JSON 反序列化来（比如用
protojson.Unmarshal），之后调proto.Marshal前务必调proto.Validate(msg)（需启用go_proto_validate插件） -
proto.Size(msg)是安全的，不 panic，可放心用于缓冲区预分配；但binary.Size(msg)返回值不可信，它不按 protobuf wire format 计算
UnmarshalJSON 字段全为零，驼峰字段名映射失败
默认情况下，protojson.Unmarshal 完全按 .proto 中字段名（如 user_name）匹配 JSON key，不会做 userName → user_name 的自动转换，也不会报错，而是静默跳过。
- 必须用
protojson.UnmarshalOptions{UseProtoNames: false}（注意：不是AllowUnknownFields） - 更推荐显式配
json_name：在.proto中写string user_name = 1 [json_name = "userName"];，再配合UseProtoNames: false - 别用标准库
json.Unmarshal解析 protobuf 消息——它根本不知道XXX_unrecognized或 field tag 编码规则 -
protojson包发布时间是 2026 年 4 月 5 日，旧项目若用的是github.com/golang/protobuf/jsonpb，必须迁移到新包，否则字段映射行为不一致
最容易被忽略的是：proto3 的零值字段（如 int32 id = 1 设为 0）根本不会出现在二进制输出里，反序列化回来虽是 0，但你无法区分它是“传了 0”还是“压根没传”。这种语义差异，在调试跨服务数据流时，比任何编译错误都难定位。
