旧版 protobuf API 编译失败需全面升级：将 proto.Message 改为 protoreflect.Message，proto.MarshalTextString 改为 prototext.MarshalOptions，XXX_MessageName 等调用替换为 ProtoReflect() 链式调用并加 nil 检查；清理 replace 依赖、隔离 DTO 版本、改用 ExtensionType.Get/Set 替代 proto.GetExtension。
旧版 protobuf API 编译失败怎么办
直接报 undefined: proto.Message 或 msg.XXX_MessageName undefined，说明你还在用 v1.25 及之前的写法，而项目已升级到 google.golang.org/protobuf v1.28+。新版 runtime 彻底移除了 proto.Message 接口和所有 XXX_* 方法，不是警告，是硬性删除。
- 必须把函数参数从
func handle(m proto.Message)改成func handle(m protoreflect.Message)，并导入google.golang.org/protobuf/reflect/protoreflect -
proto.MarshalTextString(msg)永久失效，换成prototext.MarshalOptions{}.Format(m)（导入google.golang.org/protobuf/encoding/prototext） - 所有
msg.XXX_*调用都要重写：比如msg.XXX_MessageName()→msg.ProtoReflect().Descriptor().FullName()，且必须加 nil 检查：msg != nil && msg.ProtoReflect().IsValid() - 别指望生成器保留旧方法——
protoc-gen-gov1.26+ 根本不输出XXX_*，强行保留引用只会让go build直接失败
跨模块升级时 replace 指向本地旧版包导致构建失败
你在 go.mod 里写了 replace github.com/x/y => ./local/y，但本地 y 的 go.mod 还在用老 protobuf，结果主模块编译时拉进来的仍是废弃 API，panic 在运行时才暴露。
-
replace优先级高于require，但它不解决语义兼容问题——它只是把路径换了，底层依赖树没变 - 用
go list -m all | grep protobuf确认实际加载的是哪个版本；若显示v1.25.0，哪怕主模块require了v1.30.0也没用 - 临时调试可
replace，但 CI 构建前必须删掉，或用go mod edit -dropreplace=github.com/x/y清理 - 子模块自身也要升级：确保
./local/y/go.mod中require google.golang.org/protobuf v1.30.0，否则 replace 只是把问题从一处搬到另一处
RPC 接口字段升级后老客户端解析 panic
v2 版本的 .proto 新增了 optional string tag = 4;，但服务端返回 JSON 时，v1 客户端反序列化却因字段不存在而 panic ——这不是 protobuf 层的问题，是 Go 的 JSON 解码器对未知字段默认行为太激进。
- 不要依赖
json.Unmarshal的默认宽容策略；v1 响应 DTO 必须显式定义全部字段，哪怕值为空，且禁用omitempty（否则新增字段为零值时会消失，旧客户端可能误判结构） - 服务端响应前做一次字段裁剪：用
map[string]interface{}解析后再删掉 v1 不认识的 key，比靠客户端容错更可靠 - 如果用
encoding/json，给 v1 struct 加json:"-"标签屏蔽新字段；但更稳妥的是彻底隔离 DTO 类型，如UserResponseV1和UserResponseV2，不嵌套、不复用 - protobuf 本身兼容，但 Go 的 JSON 编解码是独立一层，它的契约和 proto 不等价——这点最容易被忽略
扩展字段调用 proto.GetExtension 触发 warning 且无法过严格编译
代码里还有 proto.GetExtension(msg, extField, &val)，升级到 v1.27+ 后 go build -gcflags="-e" 直接失败，因为该函数已被标记 deprecated，v1.30+ 将彻底移除。
立即学习“go语言免费学习笔记（深入）”；
- 必须改用
extField.Get(msg.ProtoReflect())，其中extField是protoreflect.ExtensionType类型，由protoc-gen-go自动生成并在init()中注册 - 若
Get返回零值且无 error，大概率是扩展类型没注册成功——检查生成代码是否包含类似func init() { proto.RegisterExtension(...)的调用 -
proto.SetExtension同理，换成extField.Set(msg.ProtoReflect(), val)，注意 val 类型必须与 extension 定义完全一致（比如string不能传*string） - 别试图封装一层兼容桥接——runtime 不再提供旧接口的 shim，桥接层自己也会在 v1.30+ 编译失败
go get -u 后突然中断。真正麻烦的不是改几行代码，而是那些藏在中间件、工具函数、测试 mock 里的隐式依赖——它们不会报错，直到某次上线后第一个请求触发 panic。 
