buf 不是 protoc 替代品而是 protobuf 工程实践重定义：需正确配置 buf.yaml/buf.gen.yaml、校验 go_package 与 go.mod 一致性、设置 path 与可执行权限、使用完整插件镜像名、严格匹配模块路径、维护 buf.lock，否则生成失败或静默跳过。
Buf 不是 protoc 的替代品，而是整套 Protobuf 工程实践的重定义——不配对 buf.yaml 和 buf.gen.yaml，生成就不可靠；不校验 go_package 与 go.mod 一致性，go build 必然失败。
buf 命令找不到？PATH 和可执行权限没设对
现象是终端敲 buf version 报 command not found: buf，哪怕你已下载解压了官方二进制。这不是没装，是没“就位”。
- Linux/macOS：用
chmod +x buf加上可执行权限，再放进$PATH覆盖路径，例如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 代码，必须显式声明插件。很多人抄文档写 name: go，结果 buf generate 静默跳过——Buf 不认简写，只认完整镜像名。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 正确写法是
plugin: buf.build/protocolbuffers/go（对应protoc-gen-go）和plugin: buf.build/grpc/go（对应protoc-gen-go-grpc） - 版本号建议锁死，例如
v1.32.0；填latest可能拉到破坏性更新，导致go build报undefined: proto.Message - 若用自建插件，得配
path或executable字段，不能只靠PATH查找
go_package 和 go.mod 不一致，Buf 会静默跳过生成
Buf 对路径匹配极其严格：如果 .proto 里写 option go_package = "github.com/user/repo/api";，但你的 go.mod 第一行是 module github.com/user/repo/v2，Buf 就直接跳过该文件，且不报错——只在 buf generate -v 里提一句 skipping file: no go_package option。
-
go_package值必须与go.mod的模块路径完全一致，包括末尾斜杠、大小写、版本后缀（如/v2） - 多级包路径如
github.com/user/repo/v2/api，要求go.mod也声明为module github.com/user/repo/v2 - 临时调试可用
buf build --debug看 Buf 解析出的go_package是否是你预期的值
buf.lock 变更引发误报 BREAKING_CHANGE
buf breaking 检测不仅比对当前 .proto 文件，还依赖 buf.lock 记录的历史快照。删掉 buf.lock、升级了引用的第三方 proto 仓库，都可能触发假阳性 BREAKING_CHANGE 报告。
- 不要手动编辑或删除
buf.lock；它由buf mod update自动维护 - CI 中跑
buf breaking前，确保buf.lock已提交且与本地一致 - 若需忽略某类变更，应在
buf.yaml的breaking下配ignore，而不是绕过检测
最常被忽略的是 buf.yaml 里 build.roots 的路径是否真能覆盖所有 .proto 文件——写错一级目录，buf build 就报 no files to compile，而你还在检查语法。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
