Buf 完整指南：如何把 Protobuf 工程从手写脚本带到一站式工具链

Buf 完整指南：如何把 Protobuf 工程从手写脚本带到一站式工具链

【免费下载链接】bufThe best way of working with Protocol Buffers.项目地址: https://gitcode.com/GitHub_Trending/bu/buf

Buf 是 Protocol Buffers 的现代化工程工具链：它把你仓库里的 .proto 文件纳入一份小小的配置统一管理，把格式规整、风格检查、兼容性检查、代码生成、依赖管理统一成一组标准命令，还能让同一份定义最终发布到集中式注册中心（Buf Schema Registry，简称 BSR），变成团队都能复用的版本化 API。

项目定位：一条配置贯穿始终的 Protobuf 工具链

Buf 要解决的问题很具体：如果你今天还在围着protoc -I拼 shell 脚本、逐台机器装插件、靠人肉同步 .proto 文件，Buf 就是替代方案。它沿用你熟悉的 schema 语言和 protoc 插件模型，但把零碎件换成"模块 + 工作区 + 配置文件"的组合——同一份 buf.yaml 让编译、lint、兼容性检查、生成对齐同一份输入，同一份 buf.gen.yaml 成为代码生成的唯一事实来源，本地文件到受治理的 API 之间只剩标准命令。在源码层面，lint 与破坏性变更检测的规则引擎位于 private/bufpkg/bufcheck，生成引擎位于 private/bufpkg/bufgen。

环境准备：用 Homebrew 装好 Buf 并验证版本

前提是你的 macOS 或 Linux 机器上装有 Homebrew（Buf 同样提供 Windows、Docker、npm 等安装渠道，本文走 Homebrew 这条线）。执行：

brew install bufbuild/buf/buf

这一条命令装下的不止buf主命令，还包括 lint 与破坏性检测插件protoc-gen-buf-lint、protoc-gen-buf-breaking，以及 Bash、zsh、Fish、PowerShell 的补全脚本。接着验证是否生效：

buf --version

看到正常的版本号输出，环境就就绪了。

核心任务演练：从初始化工作区到产出代码的最小链路

假设你刚建好一个空目录，里面放着几个 .proto 文件（比如一个声明了 message 和 service 的 example.proto）。接下来按顺序走五步，每步都是一条命令的事。

第 1 步：初始化工作区配置。先让 Buf 知道哪些目录是模块：

buf config init

执行后项目根目录会多出 buf.yaml（多模块项目还会生成 buf.work.yaml）。本仓库根目录的 buf.yaml 就是可以直接对照的范例：v2 格式，声明一个模块并启用 STANDARD lint 集合。

第 2 步：先编译，再规整。动生成之前先确认整体能编译通过：

buf build

成功时不会打印任何错误，意味着所有 import 都已解析。趁热把格式统一掉：

buf format -w

-w会把规整结果直接写回文件，跑完后 .proto 的缩进、语句顺序全部归一，diff 里就是这次改动的全部内容。

第 3 步：风格检查。格式管"好不好看"，lint 管"API 形状对不对"：

buf lint

它会按 buf.yaml 里声明的规则集逐项检查，有问题会直接指出文件和行号，趁你还在编辑时修最省事。

第 4 步：兼容性检查。如果目录已有 Git 历史，可以拿当前 schema 和上一个版本比一比，确认改字段名、改类型没有踩到兼容红线：

buf breaking --against '.git#branch=main'

无输出即没有不兼容变更。--against可以指向 Git 分支、本地目录或注册中心模块，所以这条命令在你本机和 CI 里写法完全一致。

第 5 步：产出结果。到这一步，如果目录里已有 buf.gen.yaml，一条命令就能把定义变成代码：

buf generate

生成物落到配置文件里声明的各个输出目录，不再需要你手写一串插件命令。

典型工作流：两个真实任务场景

为多语言项目一键生成代码

痛点：团队里每台机器都要各自装生成插件，生成命令散落在冗长的 shell 脚本中，而 go_package 这类语言专属选项写在 .proto 里又很难同时照顾多语言。

Buf 的解法是把"用什么插件、输出到哪、带什么选项"全部收进版本化配置。以"Go 类型 + ConnectRPC 处理器"为例，最小配置大致长这样：

version: v2 managed: enabled: true plugins: - local: protoc-gen-go out: gen/go opt: - paths=source_relative - local: protoc-gen-connect-go out: gen/go inputs: - directory: proto

managed 模式让语言专属选项留在配置文件而不是 .proto 里；插件既可以像上面这样本地运行，也可以用托管在注册中心的远程插件，那样机器上连插件二进制都不用装。执行buf generate后，生成代码就落在 gen/ 下。仓库自带了一份 Go 生成模板可供参考：etc/template/buf.go.gen.yaml，还有只生成客户端的变体 etc/template/buf.go-client.gen.yaml。想加第二种语言，只需再补一个插件块，输入与选项都不用再动。

把协议发布到注册中心供他人复用

痛点：别的团队要用你这套 message 定义，大家就开始跨仓库拷贝 .proto 或手工 vendor，版本一改就得两边手动同步，时间一长必然漂移。

正确做法是把模块发布到 Buf Schema Registry：

buf login buf push

推送成功后，这个模块就成为组织内的权威来源。其他仓库在 buf.yaml 中把它声明为依赖、用 buf.lock 锁定版本，构建时自动拉取，彻底告别手工拷贝；消费方甚至可以直接用常规包管理器安装注册中心产出的 SDK，连生成环节都省了。

周边与生态：Buf 还能和谁搭配

和 ConnectRPC：一份定义，三种传输协议

.service 定义写一次，ConnectRPC 就能同时产出支持 Connect（纯 HTTP/JSON）、gRPC、gRPC-Web 三种协议的客户端与服务端，不需要再维护第二份服务定义。上面场景一里加一个 connect-go 插件就打通了这条线。

和 Protobuf-ES：JS/TS 的现代运行时

对 JavaScript 和 TypeScript 项目，Protobuf-ES 提供了现代化的运行时与生成器，让浏览器和 Node 端用 Protobuf 的类型清晰、体积可控。和 Buf 组合后，同一份定义可以同时驱动后端与前端。

和 Protovalidate：把校验规则写进 schema 里

Protovalidate 允许把字段级校验规则（非空、取值范围、正则匹配等）直接标注在 schema 上，且校验行为在各语言间保持一致，省去每个服务各自重写一遍检查逻辑的麻烦。

想继续深入，可以从 README.md 看起；Buf 自身的注册中心 API 定义在 proto/buf/alpha，版本变更历史见 CHANGELOG.md。

【免费下载链接】bufThe best way of working with Protocol Buffers.项目地址: https://gitcode.com/GitHub_Trending/bu/buf