必须用 protoc-gen-go 生成 .pb.go 文件，仅靠 go install 或手写结构体会导致序列化 panic 或字段丢失；新版 protoc（≥3.15）需拆分 --go_out 和 --go-grpc_out 参数，且必须配 --go_opt=paths=source_relative 和正确格式的 option go_package（如 "./api;api"），否则 import 路径错乱、包声明错误或编译失败。
生成 .pb.go 文件必须用 protoc-gen-go，不能只靠 go install 或手动写结构体——否则序列化会 panic 或字段丢失。
protoc 命令必须拆开 --go_out 和 --go-grpc_out
新版 protoc（≥ 3.15）已移除 plugins=grpc 语法，硬写会报错：--go_out: protoc-gen-go: plugins are not supported。
- 正确写法是两个独立参数：
protoc --go_out=. --go-grpc_out=. - 必须配
--go_opt=paths=source_relative，否则生成的import路径错乱，比如本该import "myproj/api"却变成import "api" - 如果用了 gRPC，
protoc-gen-go-grpc必须单独安装，且版本要和google.golang.org/grpc兼容（2026 年主流用 v1.6x）
option go_package 不写或写错，生成的代码根本 import 不进来
这是最常被跳过的一步，但直接导致编译失败或运行时 proto.Marshal panic：找不到消息类型注册信息。
- 格式必须是
option go_package = "./api;api";—— 前半段是相对模块根目录的输出路径，后半段是 Go 包名 - 不能只写
option go_package = "api";，这会让protoc忽略模块路径，生成错误的包声明 - 若
.proto在proto/user/v1/user.proto，推荐写成option go_package = "myorg.com/proto/user/v1;userv1";
proto.Marshal 失败常见原因不是数据问题，而是类型未注册或 nil 指针
即使结构体字段全填了，proto.Marshal 仍可能 panic：panic: proto: no encoder for ... 或 nil pointer dereference。
- 确保传入的是指针：
proto.Marshal(&msg)，不是proto.Marshal(msg) - 嵌套消息字段为
nil是合法的，但某些旧版生成代码（如github.com/golang/protobuf）不处理，建议统一升级到google.golang.org/protobuf - 如果用了
oneof字段，必须显式设置其中一个子字段，否则序列化后字节为空，反序列化时无法还原 - 自定义选项（如
validate.rules）不影响序列化本身，但若校验失败，protojson.Unmarshal会报错，而proto.Unmarshal不校验——这点容易混淆
真正麻烦的从来不是怎么写 protoc 命令，而是 go_package 路径、模块名、文件存放位置三者对不上——只要有一处脱节，生成的代码就进不了 go build 流程，更别说跑通 proto.Marshal 了。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
