先装 protoc 编译器本体，再装 Go 插件：macOS 用 brew install protobuf，Linux/Windows 下载二进制包；go install 两个插件 protoc-gen-go 和 protoc-gen-go-grpc；生成时用 --go_out=. --go-grpc_out=.。
protoc 命令找不到：先装 protoc 本体，别只 pip install
很多同学在 macOS 或 Linux 上执行 protoc --version 报错“command not found”，本质是没装 protoc 编译器本身，而误以为 pip install protobuf 就够了——那是 Python 的 runtime 库，和编译器无关。
- macOS 推荐用
brew install protobuf（注意不是brew install proto） - Linux 用官方二进制包最稳：下载
protoc-*.zip，解压后把bin/protoc加入$PATH - Windows 用户直接下
protoc-*.zip，解压后把bin目录加进系统环境变量 - 验证：运行
protoc --version应输出类似libprotoc 3.21.12，版本 ≥ 3.15 才支持 gRPC-Go v1.50+ 的新插件协议
go install grpc-go 的 protoc-gen-go 和 protoc-gen-go-grpc 失败
Go 官方插件已拆分为两个独立命令：protoc-gen-go（生成 pb.go）和 protoc-gen-go-grpc（生成 gRPC service 接口），不能只装一个。常见失败原因是 GOPROXY 配置不当或 Go 版本不匹配。
- 确保
GO111MODULE=on（Go 1.16+ 默认开启，但 CI 或旧 shell 可能关着） - 用
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest安装基础插件 - 再用
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest安装 gRPC 插件 - 检查是否进 PATH：
which protoc-gen-go和which protoc-gen-go-grpc都应返回路径（通常是$GOPATH/bin） - 如果提示 “cannot find module providing package”，大概率是 GOPROXY 被墙，临时设为
export GOPROXY=https://goproxy.cn,direct
protoc 命令生成时报错 “unrecognized option: -go-grpc_out”
这是插件名和参数格式不匹配的典型表现。v1.50+ 的 gRPC-Go 要求显式指定插件路径，且参数名必须带 _out 后缀，但插件名本身不含下划线。
- 错误写法：
protoc --go-grpc_out=. xxx.proto→ 报 unrecognized option - 正确写法：
protoc --go_out=. --go-grpc_out=. xxx.proto（两个独立参数） - 如果自定义插件路径（比如不在 $PATH），要加
=指定：protoc --go_out=plugins=grpc:. --go-grpc_out=. xxx.proto（注意plugins=grpc是旧写法，仅兼容 v1.4x；新项目请用上面两段式） - 生成目录必须存在，
protoc不会自动创建./pb这类子目录
生成代码里没有 RegisterXXXServer 函数？检查 import 和 plugin 版本对齐
生成的 *_grpc.pb.go 文件里缺服务注册函数，通常不是语法问题，而是 protoc-gen-go-grpc 版本太低，或 google.golang.org/grpc 依赖没拉对。
立即学习“go语言免费学习笔记（深入）”；
- 确认
protoc-gen-go-grpc版本 ≥ v1.3.0（protoc-gen-go-grpc --version） - 检查
go.mod中google.golang.org/grpc是否 ≥ v1.50.0（老版本用RegisterXXXServer，新版本改用MustRegisterXXXServer或直接传grpc.Server） -
import语句必须包含google.golang.org/grpc，否则生成器可能跳过 server stub - proto 文件中
service块必须有至少一个 RPC 方法，空 service 不会生成 Register 函数
插件链里任意一环版本错位，都会让生成结果“看起来像跑通了，实际不能用”。建议所有 protoc 相关工具统一用 latest，而不是混用 tagged release。
