Buf：现代 Protobuf 工具链

bufbuild/buf 在 GitHub 上已经拿到 11,226 Star。它把自己定位为现代 Protobuf 工具链，替代日常开发中围绕 protoc 的脚本和手动流程。从 v1.0 开始，Buf CLI 承诺在同一大版本内不做破坏性变更，beta 命令除外。

1、这项目是干嘛的

Buf 解决的是 Protobuf 工作流。它把编译、格式化、lint、破坏性变更检测、代码生成、依赖管理和 Buf Schema Registry 客户端装进一个 CLI。核心思路是把 .proto 文件从本地编辑到发布治理化 API 的整条链路串起来。

如果你现在还在用 shell 脚本调用 protoc -I，Buf 提供的是同一份 schema 语言、同一套生成插件模型，但零件更少，路径更直接。它不会因为 import 顺序不同而给出不同结果，也不需要每台机器都维护一组插件版本。

2、为什么要用它

用 protoc 的团队通常会遇到几个麻烦：import 路径靠 -I 参数维护，顺序一变行为就可能变；每台机器和 CI runner 都要装对应版本的插件；字段兼容性要到客户端报错或序列化异常才能发现；跨仓库共享 .proto 文件时不是拷贝就是手写 vendor。

Buf 把这些步骤收进配置。模块在 buf.yaml 里声明一次，编译器自己发现文件并拒绝歧义 import。lint 和 breaking 检查可以在本地、编辑器、CI 和 BSR 上跑。代码生成通过 buf.gen.yaml 描述，插件可以是本地二进制，也可以是 BSR 上的远程插件。依赖直接声明在 buf.yaml 里，版本锁在 buf.lock 中。README 里列了一张对比表：找文件、编译、风格检查、兼容性、代码生成、依赖管理、API 消费者、治理这几件事，用 protoc 要拼多个工具，用 Buf 则是一个配置加一组命令。

3、核心工作流

Buf 把目录树看成一个 module，把项目看成一个 workspace。一个基础的 buf.yaml 就能让 build、lint、breaking、generate、push 这些命令对同一份输入达成一致。

常用命令如下：

buf build
buf format -w
buf lint
buf breaking --against '.git#branch=main'
buf generate
buf push

buf build 编译 workspace。buf lint 在编辑阶段就拦截 API 形状问题。buf breaking 把当前 schema 和旧版本对比，标出 source、JSON 或 wire 格式上的不兼容。buf generate 按配置跑 protoc 插件。buf push 把模块发布到 BSR。

4、代码生成与破坏性变更

buf generate 兼容普通 protoc 插件模型，但把生成逻辑搬进版本化配置。远程插件意味着不需要在每台机器上维护生成器二进制。managed mode 让 API 生产者把语言相关的文件选项从 .proto 里剥离，消费者仍能得到正确的生成包名。

破坏性变更可以分成不同层面。重命名字段可能只破坏生成源码，不改变 wire 格式；把 int32 改成 string 则会让所有已序列化消息失效。buf breaking 用 FILE、PACKAGE、WIRE_JSON、WIRE 这几类规则把差异显式化。--against 支持 Git 分支、BSR 模块、tarball、zip 或预构建的 Buf image。同一条命令在笔记本、CI 和发布自动化里都能用。

5、安装与生态

安装最方便的方式是用 Homebrew：

brew install bufbuild/buf/buf

初始化后跑一遍常用检查：

buf config init
buf build
buf format -w
buf lint
buf breaking --against '.git#branch=main'

Buf 周边还有 ConnectRPC、Protobuf-ES、Protovalidate 等项目。ConnectRPC 用 Protobuf schema 生成同时支持 Connect、gRPC、gRPC-Web 的 HTTP API；Protobuf-ES 给 JavaScript 和 TypeScript 提供现代 Protobuf 运行时；Protovalidate 把校验规则写进 schema，跨语言统一执行。BSR 则把这些能力串成一条线：模块上传后自动编译、生成文档、解析依赖，并输出多种语言的 SDK。

6、适合谁用

• 用 Protobuf 做多语言微服务或 API 治理的团队
• 还在用 shell 脚本绕 protoc，想减少脚本和配置碎片的人
• 需要把 schema 当作单一事实来源，驱动代码生成、文档、SDK 和校验的项目

核心 CLI 功能不需要 BSR 账号。登录注册表后，可以使用分发、远程插件、生成 SDK、托管文档、私有模块依赖解析和服务器端检查。

核心 CLI 功能不需要 BSR 账号。登录注册表后，可以使用分发、远程插件、生成 SDK、托管文档、私有模块依赖解析和服务器端检查。