Buf 是什么：Protobuf 生态里的 CLI 与 Schema注册表（BSR）

如果你用 Protocol Buffers（protobuf） 描述 API 或事件，迟早会碰到：本地 protoc 命令一长串、插件版本各项目不一致、.proto 依赖从哪拉、改了一个字段算不算破坏性变更……Buf 就是围绕这些问题长出来的一套工具与托管服务：用统一的方式管理 schema、生成代码、做检查与协作。

常说的 Buf 里，和日常开发最相关的是两块：

• Buf CLI：本机命令行工具，替代或封装「手写一长串 protoc」的工作流。
• Buf Schema Registry（BSR）：托管在 buf.build 上的 Schema 注册表（可理解为 protobuf 的「模块仓库 + 文档 + 依赖解析」），和 CLI 通过模块名、版本规则配合使用。

下面分开说明它们做什么、和「裸用 protoc」相比多解决了什么。

Buf 在 protobuf 生态里扮演什么角色？

Protobuf 本身是 IDL（接口描述语言）+ 二进制编码格式：你用 .proto 文件定义消息与服务，再用编译器生成各语言代码。官方工具链核心是 protoc + 各类 插件（如 Go、Java、各类 gRPC 插件）。

Buf 不改变 .proto 语法本身，而是在其之上提供：

可以把 Buf 理解成：让 protobuf 工作流更像现代语言的工具链（格式化、静态检查、语义化版本、依赖解析），而不是每人一份魔改脚本。

Buf CLI：本机上的「一把梭」工具

Buf CLI 是开源命令行程序（见 bufbuild/buf），安装后主要和仓库里的配置文件打交道。

常见配置文件

• buf.yaml：模块根配置。常见内容包含：
  • 模块路径（name，若对接 BSR 则往往是 buf.build/组织/模块名 这类坐标）；
  • Lint 与 breaking 规则；
  • deps：依赖哪些已发布在 BSR 上的模块（版本用 BSR 的约定管理）。
• buf.gen.yaml：代码生成声明——用哪些 protoc 插件、输出到哪个目录、策略（managed 等）。执行 buf generate 时会读它，避免团队里每人记一套 protoc 参数。

此外还有 buf.lock（锁定依赖解析结果）等，保证可复现构建。

你会经常用到的命令（概念层面）

整体上：CLI 负责「在你电脑 / CI 里把 schema 管好」——检查、格式化、生成、防手滑破坏兼容。

Buf Schema Registry（BSR）：buf.build 上的「注册表」

BSR（Buf Schema Registry）是 Buf 提供的托管服务，站点即大家常说的 buf.build。它解决的是跨团队、跨仓库共享 .proto 时的问题：不再靠拷贝文件或私有 Git 子模块硬拉，而是把 schema 当作带版本的模块发布上去。

BSR 大致提供什么？

• 模块与版本：把你的 buf 模块推送到 BSR，得到稳定坐标（如 buf.build/acme/weather）与可引用的版本（标签、提交等模型以官方文档为准）。
• 依赖解析：别的项目在 buf.yaml 里声明 deps，buf 从 BSR 拉取依赖并锁定，CI 可复现。
• 浏览与文档：Web 上查看模块、消息与服务的文档化展示（对协作很友好）。
• 与生成链集成：例如远程插件、托管场景下的生成能力等（能力随产品与计划变化，以 BSR 文档 为准）。

CLI 与 BSR 的关系可以记一句：CLI 在本地执行规则与生成；BSR 在云端托管模块、版本与依赖。没有 BSR，你仍可用 Buf CLI 管自家单体仓库；有了 BSR，多仓库、多团队共享 API 会轻松很多。

名字怎么记？

• buf.build：Buf 公司网站与 BSR 入口，也是浏览器里看模块的地方。
• 「Registry」：在文档和产品里对应 Buf Schema Registry（BSR），不要和容器领域的 Docker Registry 混淆——这里存的是 protobuf schema模块，不是镜像。

什么时候值得上 Buf？

值得考虑：

• 多人协作、多服务共享同一套 .proto，希望依赖清晰、可审计。
• 希望在 CI 里强制 lint + breaking check，避免线上悄悄改坏字段编号或类型。
• 想统一 buf generate，告别每人一套 protoc 脚本。

可以暂缓：

• 只有一个很小的 .proto、且不打算引入团队规范；此时学 Buf 的收益相对有限（但仍可用 CLI 只做 format/lint）。

小结

延伸阅读

• Buf 文档总览
• Buf CLI 安装与入门
• Buf Schema Registry（BSR）
• GitHub：bufbuild/buf