protoc 命令找不到是因未加入 PATH，需手动将二进制路径（如 /usr/local/bin 或 $HOME/bin）加入 PATH；macOS 用 brew install protobuf 最省事；Windows 安装时须勾选「Add protoc to system PATH」。
protoc 命令找不到：PATH 和二进制位置是关键
装完 protoc 却提示 command not found，大概率是没加到 $PATH。官方预编译包解压后只是个孤立的二进制，不会自动注册。
- Linux/macOS 下推荐解压到
/usr/local/bin（需sudo）或$HOME/bin，然后确保该路径在$PATH中（检查echo $PATH） - macOS 用 Homebrew 装最省事：
brew install protobuf，自动处理路径 - Windows 用户别只双击运行安装包——得勾选「Add protoc to system PATH」，否则 cmd/PowerShell 里照样找不到
protoc - 验证是否生效：
protoc --version必须输出类似libprotoc 24.4，而不是command not found
protoc-gen-go 报错 “plugin not found” 或 panic
protoc-gen-go 不是 protoc 自带的插件，它得单独安装、且版本必须和 google.golang.org/protobuf 兼容。常见报错如 protoc-gen-go: plugin failed with status code 1 或直接 panic，基本都卡在这儿。
- Go 1.16+ 推荐用 Go Module 方式安装：
go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.34.2（注意指定明确版本，别用@latest） - 安装后检查
$GOBIN（默认$GOPATH/bin）下是否有protoc-gen-go文件，并确保该目录在$PATH中 - 如果项目用了
google.golang.org/protobufv1.33.x，就别装 v1.34.x 的插件——生成代码会出 runtime panic，因为MarshalOptions等结构有变更 - 执行生成命令时，
--go_out后面跟的其实是插件名，不是路径：protoc --go_out=. --go_opt=paths=source_relative xxx.proto，不是--go_out=protoc-gen-go=.
Go 模块中 import path 错乱导致编译失败
生成的 .pb.go 文件里 import 的包路径，取决于 .proto 文件里的 go_package option。不写或写错，会导致 Go 编译器找不到符号。
- 每个
.proto文件顶部必须声明：option go_package = "github.com/yourorg/yourrepo/pb"; - 这个路径要和你实际的 Go Module 路径一致；如果模块是
github.com/yourorg/yourrepo，那go_package就不能写成"pb"或"./pb" - 生成命令中的
--go_out路径必须匹配go_package的最后一级（比如go_package = "xxx/pb"，就得--go_out=./pb），否则文件放错位置，import 仍会失败 - 多级目录 proto（如
api/v1/user.proto）建议统一用相同go_package前缀，避免生成分散的包
protoc-gen-go-grpc 和 gRPC 接口生成容易漏掉依赖
只装 protoc-gen-go 是不够的——如果 proto 定义了 service，还得额外生成 gRPC stub，这需要另一个插件。
- 安装插件：
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.4.0（版本需与google.golang.org/grpc运行时一致） - 生成命令要加两组参数：
protoc --go_out=. --go-grpc_out=. --go_opt=paths=source_relative --go-grpc_opt=paths=source_relative xxx.proto - 对应依赖也得加进
go.mod：google.golang.org/grpc+google.golang.org/protobuf，缺一不可 - 注意
go-grpc_out默认生成的是XXXClient/XXXServer接口，但实际实现时还要手动实现UnimplementedXXXServer，不然 gRPC server 启动会 panic
真正麻烦的不是装几个命令，而是版本对齐：protoc 版本、protoc-gen-go 版本、protobuf runtime 版本、gRPC runtime 版本，四者稍有错位，就会在生成或运行时才暴露问题。建议把这几个版本号写进项目根目录的 PROTOBUF_VERSIONS.md 里，下次升级前先比对。
