Buf命令不识别需检查PATH和可执行权限；buf.gen.yaml插件须用完整名称如buf.build/protocolbuffers/go；go_package必须与go.mod完全一致；buf.lock变更会导致误报BREAKING_CHANGE。
Buf CLI 安装后 buf 命令不识别？检查 PATH 和二进制权限
常见错误现象是执行 buf version 报错 command not found: buf，哪怕下载解压了官方二进制。根本原因不是没装，而是没放进 $PATH，或 macOS/Linux 下缺少可执行权限。
- Linux/macOS：用
chmod +x buf确保二进制可执行，再用sudo mv buf /usr/local/bin/或加到$HOME/bin并确保该路径在$PATH中 - Windows：把
buf.exe放进系统环境变量PATH覆盖的目录（如C:\Windows\System32），别只丢在下载文件夹里 - 验证方式：终端新开一个窗口，运行
which buf（macOS/Linux）或where buf（Windows），有输出才算真正就位
buf.gen.yaml 里 plugin 配置不生效？注意 Go 插件名和版本绑定
Buf 默认不生成 Go 代码，必须显式声明 protoc-gen-go 和 protoc-gen-go-grpc 插件。很多人照抄文档写 name: go，结果生成失败——因为 Buf 不认简写，必须用完整插件名。
- 正确写法是
name: buf.build/protocolbuffers/go（对应protoc-gen-go）和name: buf.build/grpc/go（对应protoc-gen-go-grpc） - 这两个插件由 Buf 官方托管，无需本地安装
protoc-gen-go；但若你用自建插件，得配path或executable - 版本号不能乱填：
v1.32.0是目前兼容 Go 1.21+ 的稳定版，填latest可能拉到不兼容的预发布版，导致go build报undefined: proto.Message
Go 模块路径和 go_package 不一致？Buf 会静默忽略生成
Buf 不像原生 protoc 那样容忍路径混乱。如果 .proto 文件里的 option go_package = "github.com/user/repo/api"; 和你当前 Go 模块的 go.mod 声明不匹配，Buf 会跳过该文件生成，且不报错——只在 buf generate -v 里提一句 skipping file: no go_package option。
- 必须保证
go_package值与go.mod第一行的模块路径完全一致（包括末尾斜杠、大小写） - 多级包路径如
github.com/user/repo/v2/api，需确保go.mod也声明为module github.com/user/repo/v2，否则生成的.pb.go里 import 路径错乱，go build直接失败 - 临时调试可用
buf build --path api/foo.proto -o - | jq .看 Buf 解析出的go_package是否是你预期的值
为什么 buf lint 报 BREAKING_CHANGE 却没改任何字段？检查 buf.lock 和依赖变更
Buf 的 breaking change 检测不仅看当前 proto 文件，还依赖 buf.lock 记录的历史快照。如果你删掉 buf.lock 或更新了依赖仓库（比如升级了引用的第三方 proto 包），Buf 会误判为“从无到有”的破坏性变更。
立即学习“go语言免费学习笔记（深入）”；
- 运行
buf mod update同步依赖并重写buf.lock，再跑buf lint，多数假阳性消失 - 若确实要忽略某类变更（如仅增字段），可在
buf.yaml里加ignore_only: ["WIRE_JSON"]，但别关BREAKING_CHANGE类型——它真会引发 runtime panic - CI 中务必校验
buf.lock是否被意外提交，否则不同人本地buf generate输出可能不一致
Buf 工具链的“现代化”不在命令多酷炫，而在它把很多隐性依赖（比如模块路径、锁文件、插件版本）全摊开管起来了。漏掉其中一环，生成的代码就可能编译不过，或者上线后 panic。最常卡住人的，其实是 go_package 和 buf.lock 这两个看着不起眼的点。
