Kratos v2.x要求protoc≥3.21且protoc-gen-go严格为v1.31，版本错配会导致.pb.go生成失败或字段缺失；需人工核对两个工具版本，并确保go_package、路径、插件（含protoc-gen-go-http）全部正确。
protoc 和 protoc-gen-go 版本必须严格匹配
Kratos v2.x 对 Protobuf 工具链极其敏感，不是“装了就能用”，而是“版本错一个就生成失败”。常见现象是 make api 后只生成空的 xxx.pb.go，或编译时报 undefined: xxxRequest —— 这往往不是 proto 写错了，是工具链没对上。
-
protoc --version必须 ≥3.21；低于此版本无法解析google/api/annotations.proto，导致 HTTP 路由代码完全不生成 -
protoc-gen-go必须锁定为v1.31（不是v1.31.0，也不是v1.32+）；v1.32+因google.golang.org/protobuf接口变更，会跳过字段生成，只留个壳 - 验证方式：分别执行
protoc --version和protoc-gen-go --version，两个输出都要人工核对，别信go install的成功提示
proto 文件里 import 的第三方定义找不到
报错如 google/protobuf/descriptor.proto: File not found 或 IDE 里 import "google/api/annotations.proto" 被标红，本质是 protoc 找不到内置 proto 路径。这不是项目问题，是本地安装不完整。
- 预编译版
protoc必须把include/google/目录完整复制到系统 include 路径（如/usr/local/include），否则所有带google/前缀的 import 都失效 - 国内用
kratos new拉模板时若超时，可能静默漏掉third_party/目录；手动检查项目根目录是否存在该文件夹，缺了就从 Kratos 官方 third_party 补全 - 如果用
buf替代protoc，需在buf.yaml中显式配置deps引入buf.build/googleapis/googleapis等远程模块
go_package 不一致导致 pb.go 编译后无法 import
proto 文件顶部的 option go_package 和实际生成路径、Go import 路径三者不一致，是运行期 panic 的高频原因，典型错误是 unknown field 'xxx' in conf.Config。
-
option go_package = "xxx/yyy;zzz"中的zzz是 Go 包名，必须和生成文件第一行package zzz完全一致（大小写、下划线都不能差） - 生成命令必须加
paths=source_relative，例如：protoc --go_out=paths=source_relative:. xxx.proto；漏掉它会导致生成路径按绝对路径算，internal/conf/conf.pb.go可能被写进conf/子目录而非预期位置 - 改完
.proto后，先手动删掉旧的.pb.go文件再重跑生成；kratos proto server默认不覆盖，容易残留旧结构
proto-gen-go-http 插件缺失导致 HTTP 路由不生成
gRPC 接口能调通但 curl http://... 返回 404，且 api/v1/xxx_http.pb.go 不存在，大概率是插件没装全，而非路由注册逻辑出错。
- 必须同时安装两个插件：
protoc-gen-go（负责.pb.go）和protoc-gen-go-http/v2（负责_http.pb.go）；只装前者，make api会静默跳过 HTTP 层 - 安装命令应为：
go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.31+go install github.com/go-kratos/kratos/cmd/protoc-gen-go-http/v2@latest - 确认插件在
$PATH下可执行：which protoc-gen-go-http有输出才算真正装好；很多 CI 环境里go install成功但未生效到 PATH
复杂点在于：这些版本和路径约束是**链式生效**的——protoc 版本错，protoc-gen-go-http 就收不到输入；go_package 错，生成的代码就进不了 Wire 注入链；任何一个环节断掉，错误都表现为下游的“找不到符号”或“panic”，而不是清晰的“请升级 protoc”。
