protoc-gen-go 版本必须与 google.golang.org/protobuf 运行时严格对齐，如 v1.30.0 对应 v1.30.0；旧 github.com/golang/protobuf 已归档，应统一迁移到新版；插件版本无法靠 go.mod 锁定，需通过本地 bin/ 目录+显式路径调用，并在 CI 中校验 protoc、插件及运行时三者版本一致性。
protoc-gen-go 版本不匹配导致生成代码失败
Go Modules 本身不管理 protoc 插件的二进制版本，只管 Go 依赖。你用 go get github.com/golang/protobuf/protoc-gen-go@v1.5.2 安装的插件，和 google.golang.org/protobuf 的 Go 运行时版本必须对齐——否则 protoc --go_out=. 会报 panic: interface conversion: descriptor is *desc.MessageDescriptor, not *descriptorpb.DescriptorProto 这类运行时 panic。
- Go 模块中声明
google.golang.org/protobuf v1.30.0→ 应配protoc-gen-go v1.30.0（注意：不是v1.3.0） - 旧项目还在用
github.com/golang/protobuf？对应插件是protoc-gen-go的v1.5.x分支，但该仓库已归档，不能再用go get直接安装新版本 - 推荐统一迁移到
google.golang.org/protobuf+protoc-gen-gov1.30+，否则go mod tidy会把两个 protobuf 运行时都拉进来，引发冲突
如何锁定 protoc-gen-go 的二进制版本
不能靠 go.mod 锁定，得靠本地可执行文件路径 + 显式版本控制。最稳妥的方式是：把插件二进制放在项目根目录下 bin/，并用 Makefile 或 shell 脚本封装调用逻辑。
- 下载指定版本：
curl -sSL https://github.com/protocolbuffers/protobuf-go/releases/download/v1.30.0/protoc-gen-go-v1.30.0-linux-x86_64 > bin/protoc-gen-go（macOS 改后缀为-darwin-arm64） -
chmod +x bin/protoc-gen-go，然后在protoc命令中显式指定路径：protoc --plugin=protoc-gen-go=./bin/protoc-gen-go --go_out=. *.proto - 避免用
$PATH查找插件——CI 环境或不同开发者机器上which protoc-gen-go结果不可控 - 别把
bin/protoc-gen-go提交进 Git（太大），改用.gitignore忽略，再配scripts/install-protoc-gen-go.sh自动下载校验
go install 与 go get 的陷阱
go install 在 Go 1.16+ 后默认只从 main 包构建，但它仍会读取当前模块的 go.mod 来解析依赖版本——这容易误伤。
- 执行
go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.30.0时，如果当前目录有go.mod且其中google.golang.org/protobuf是 v1.28.0，go install可能降级插件依赖，导致生成器内部 panic - 安全做法是：**cd 到空目录再执行
go install**，或加-mod=mod强制忽略当前模块：go install -mod=mod google.golang.org/protobuf/cmd/protoc-gen-go@v1.30.0 -
go get已废弃用于安装命令，它会修改当前模块的go.mod，造成无关变更，一律禁用
CI/CD 中确保 protoc 和插件版本一致
Protobuf 编译链是三段耦合：protoc 二进制、protoc-gen-go 插件、Go 运行时库。少一个对不上，就生成失败或运行时崩溃。
- CI 脚本里必须显式下载 protoc（如
v24.3），不能依赖系统包管理器（Ubuntu 的apt install protobuf-compiler版本太老） - 用
protoc --version和protoc-gen-go --version双重校验，脚本里写死检查逻辑，不通过直接 exit 1 - 生成代码的
Makefile目标要带哈希校验：bin/protoc-gen-go: | $(PROTOC_GEN_GO_URL) ; curl -sSL $(PROTOC_GEN_GO_URL) | sha256sum -c protoc-gen-go.sha256
真正难的不是装哪个版本，而是让 protoc、插件、Go 运行时、proto 文件语法（syntax = "proto3" vs "editions"）四者始终咬合。一旦其中一环升级，其他三个全得跟着动，而且没有自动提示——只能靠每次改完手动跑一遍 protoc + go build + go test。
