buf 版本演进与技术全景：从 v0.1.0 到 v1.73.0 的 Protocol Buffers 工作流变迁-平芜编程栈

开发工具
代码生成
API设计

【免费下载链接】buf

The best way of working with Protocol Buffers.

项目地址：https://gitcode.com/GitHub_Trending/bu/buf

本文以仓库根目录的 CHANGELOG.md 为骨架，系统梳理 buf 从 2019 年 v0.1.0 到 v1.73.0 的完整演进脉络。文章覆盖核心命令（build / lint / breaking / generate / format / curl / lsp）、配置体系（v1beta1 → v1 → v2）、格式与输入输出能力（binpb / txtpb / yaml / json）、Protobuf Editions 支持、managed mode、lint/breaking 规则体系、BSR 注册表命令与多平台发布等主题，并结合仓库源码（如 curl 命令实现、format 命令实现、buf.yaml）给出源码级佐证，帮助读者快速掌握 buf 的能力边界、迁移路径与版本演进逻辑。

一、为什么 CHANGELOG 值得读：版本即路线图

buf 是面向 Protocol Buffers 的现代化工具链，定位为"处理 Protocol Buffers 的最佳方式"（项目描述原文 The best way of working with Protocol Buffers）。其 CHANGELOG 记录了从 2019 年 10 月 v0.1.0 初始 beta 发布到 v1.73.0（2026-09-11）的全部变更，包含大量可直接落地的命令、配置与迁移细节：

新增能力：如buf curl（v1.12.0）、buf format（v1.2.0）、buf export（v0.48.0）、LSP（v1.43.0 beta / v1.59.0 stable）等；
配置演进：配置文件版本从v1beta1走向v1、v2，buf.yaml/buf.gen.yaml/buf.lock职责逐步清晰；
兼容承诺：v1.0.0-rc1 明确指出"希望 buf 在 v1 上稳定十年"，所有命令/flag 的弃用与迁移路径均提前警告（详见下文第九节）。

从仓库的 cmd/buf/internal/command 目录可以看到，当前命令面包括alpha/、beta/、breaking/、config/、convert/、curl/、dep/、export/、format/、generate/、lint/、lsfiles/、lsp/、mod/、plugin/、policy/、push/、registry/、source/、stats/等 20 个命令包，与 CHANGELOG 中逐版本新增的命令一一对应。

二、核心工作流命令的建立与稳定（2019–2022）

2.1 从 beta 到 v1.0.0：命令体系的两次大清洗

buf 的命令演进经历了两次大规模重命名：

第一次（v0.29.0，2020-10-30）：以"让 CLI 更自然"为目标，将buf image build迁移为buf build并支持 image 作为输入；buf check lint→buf lint、buf check breaking→buf breaking（v0.34.0 完成迁移，同时protoc-gen-buf-check-*更名protoc-gen-buf-*）；--fileflag 更名--path并扩展为可接受目录（v0.31.0）。CHANGELOG 给出的迁移示例：

# 编译当前目录文件 buf build # 等价的无参调用 buf build . # 构建 https 上的 git 仓库 buf build https://github.com/foo/bar.git # 检查当前目录相对 master 分支是否有破坏性变更 buf check breaking --against .git#branch=master

第二次（v1.0.0，2022-02-17）：正式移除 v1 前全部弃用项，包括buf login→buf registry login、buf config init→buf mod init、buf protoc被移除（CHANGELOG 说明其"没有带来超出主流 protoc 的价值，只是更快并支持并行编译"）、buf config migrate-v1beta1→buf beta migrate-v1beta1等。v1.0.0 同时将默认配置版本从v1beta1提升为v1，并新增buf completion（shell 自动补全脚本生成）、buf mod open、--disable-symlinks、--include-wkt等能力。

2.2 命令的持续补全（v1.0.0 之后）

buf generate在 v1.14.0 将--include-types统一为--type（旧 flag 保持兼容）；v1.32.0 起支持strategy、--clean、protoc_path数组形式（首元素为路径，其余为每次调用传给 protoc 的附加参数）。
buf config系列（v1.32.0）整合了buf config migrate、buf config ls-lint-rules、buf config ls-breaking-rules、buf config ls-modules（v1.34.0）、buf config init。
buf dep系列（v1.32.0 稳定）承接buf mod update/prune与buf dep graph（源自 v0.23.0 的buf beta graph，v1.42.0 起支持--format，默认dot、可选json）。
buf export（v0.48.0）导出可被 protoc 免-I直接构建的文件集，支持--exclude-imports与--path；v1.56.0 新增--all以包含非 proto 源文件。
buf stats（v1.17.0 起buf beta stats，v1.55.0 转正）输出模块统计信息。

三、配置体系的演进：v1beta1 → v1 → v2

3.1 版本与文件职责

文件	职责	关键里程碑
`buf.yaml`	模块/工作区配置：lint、breaking 规则、依赖、includes/excludes	v0.25.0 引入`v1beta1`版本概念；v0.44.0 曾短暂改名`buf.mod`又回退；v0.55.0 起强制要求`version:`字段；v1.32.0 支持`v2`
`buf.gen.yaml`	代码生成模板：plugins、managed mode、clean	v1.32.0 支持`v2`；v1.34.0 支持`protoc_path`数组
`buf.work.yaml`	多模块工作区	v0.45.0 从`buf.work`统一为`buf.work.yaml`
`buf.lock`	依赖锁定（ModulePin、b3 digest）	v1.0.0-rc12 移除`branch`字段；v1.0.0-rc9 起 digest 编码`buf.yaml`中的 name/lint/breaking 配置
`buf.policy.yaml`	BSR 策略（v1.65.0 起`buf registry policy`）	与 LSP 联动

仓库自身根目录的 buf.yaml 就是一份v2配置的活样例：

version: v2 modules: - path: proto name: buf.build/bufbuild/buf lint: use: - STANDARD - UNARY_RPC disallow_comment_ignores: true breaking: use: - WIRE_JSON ignore_unstable_packages: true

3.2 v2 配置的关键新增

v1.32.0 是配置体系的分水岭，引入v2版本（同时提供buf config migrate一键迁移）：

includes键（v1.39.0）：模块配置可指定目录列表，proto 文件只有位于其中才属于该模块；与excludes并用时"在 include 内且不在 exclude 内"才算模块成员；允许多个模块配置共享同一目录路径。
clean顶层选项（v1.36.0）：等价于buf generate --clean，生成前删除各插件out指向的目录/jar/zip。
插件path数组化（v1.34.0）：path: ["go", "run", ./cmd/protoc-gen-foo]支持为本地插件传参数。
opt双形态（v0.35.0）：opt可为单字符串或字符串数组，两种写法结果一致（均产生foo=bar,baz,bat）。

3.3 依赖与锁文件行为

v1.70.0：向buf.yaml添加依赖但缺少对应buf.lock条目时直接报错。
v1.38.0：buf dep update无新依赖且不存在buf.lock时不再创建空锁文件。
v1.28.0：读取含 b1/b3 digest 的buf.lock时警告，建议运行buf mod update升级 digest。
v1.24.0：buf mod update会阻止会导致依赖间.proto冲突的更新。

四、格式与输入输出能力的扩展：binpb / txtpb / yaml / json

buf 对 Protobuf 二进制/文本序列化格式的支持经历了清晰的命名规范化：

v0.14.0：引入 zip 源格式、zstd 压缩；弃用bingz/jsongz/targz，改用format=bin,compression=gzip风格，同时承诺旧格式"永远继续工作"。
v1.24.0：bin格式正式更名binpb，.binpb成为二进制编码的规范扩展名，.bin继续被接受。
v1.25.0：新增txtpb格式（Protobuf 文本格式），.txtpb文件被自动识别，可用于build、convert、curl等所有 image 输入/输出命令。
v1.29.0：新增yaml格式，示例：buf build -o image.yaml、buf ls-files image.yaml、buf convert --type foo.Bar --from input.binpb --to output.yaml；yaml与json格式新增use_proto_names、use_enum_numbers两个序列化选项（如output.yaml#use_proto_names=true）。
v1.26.1：修复buf build -o对.txtpb扩展名的正确输出。
v1.30.0：buf generate填充CodeGeneratorRequest的source_file_descriptors字段，让插件可访问仅在源码中保留的选项；buf build新增--exclude-source-retention-options剥离此类选项。

五、Protobuf Editions 支持

v1.32.0（2024-05-16）：正式支持 Protobuf Editions（edition 2023），protoc-gen-buf-breaking与protoc-gen-buf-lint同步支持。
v1.34.0：本地代码生成代理到protoc时允许使用 Editions 语法（针对 Java/C++/Python 等生成逻辑内置于 protoc 的语言）。
v1.68.0（2026-04-14）：使用新编译器支持 Editions 2024 特性，buf format支持 Edition 2024 语法；v1.68.1 回滚新编译器报告格式并"properly ungate Editions 2024 features"；v1.68.3 修复 Edition 2024 的buf format错误处理。
v1.73.0：修复 managed mode 在 Edition 2024 文件上设置java_multiple_files（该选项在 Edition 2024 下不被允许、会导致代码生成失败）的问题。

5.1 Editions 对 breaking 规则的影响（v1.32.0 大改）

Editions 引入了 feature 概念，导致 breaking 规则体系结构性调整，且所有旧规则保持兼容：

FIELD_SAME_CTYPE→FIELD_SAME_CPP_STRING_TYPE（同时考虑ctype选项与(pb.cpp).string_typefeature）。
FIELD_SAME_LABEL→ 三个"cardinality"规则：FIELD_SAME_CARDINALITY（FILE/PACKAGE）、FIELD_WIRE_COMPATIBLE_CARDINALITY（WIRE）、FIELD_WIRE_JSON_COMPATIBLE_CARDINALITY（WIRE_JSON），可区分 map 与其他 repeated 字段、隐式与显式 presence。
FILE_SAME_JAVA_STRING_CHECK_UTF8→FIELD_SAME_JAVA_UTF8_VALIDATION。
新增 feature 相关规则：MESSAGE_SAME_JSON_FORMAT、ENUM_SAME_JSON_FORMAT、FIELD_SAME_UTF8_VALIDATION、ENUM_SAME_TYPE（open vs. closed enum）。
新增扩展（extension）支持：字段规则适用于扩展，新增EXTENSION_NO_DELETE、PACKAGE_EXTENSION_NO_DELETE（默认不启用，迁移到 v2 配置才生效）；lint 也支持顶层扩展检查；新增FIELD_NOT_REQUIRED规则禁止 proto2 的 required 与 Editions 的LEGACY_REQUIRED。

六、managed mode：自动设置文件选项

managed mode（v0.42.0 引入 beta）在生成代码时自动设置文件选项，逐版本扩展能力：

v0.42.0：managed mode beta；v0.44.0 完善 v1 规范。
选项扩展轨迹：java_package_prefix（v0.54.0）→objc_class_prefix、csharp_namespace（v0.45.0/v0.46.0 前后）→ruby_package、php_namespace、java_string_check_utf8（v0.48.0）→optimize_for支持 default/except/override 三形态（v1.11.0）→objc_class_prefix、ruby_package的 except/override（v1.12.0）→csharp_namespace的 except/override（v1.10.0）→swift_prefix（v1.62.0）。
行为细节：v1.10.0 起enabled: false不再导致buf generate失败，改为警告并忽略 managed mode 选项；v1.62.1 修复swift_prefix无覆盖时保持默认未设置的默认行为。

七、lint 与 breaking 规则体系

7.1 规则组织与默认规则概念

v1.40.0：引入"默认规则"概念——buf config ls-{breaking,lint}-rules会打印默认规则属性（未显式配置 lint/breaking 规则时生效的规则集）；同时DEFAULTlint 分类更名STANDARD（DEFAULT向后兼容、永远可用）。
v1.54.0：breaking 规则新增CSR分类。
v0.36.0/v0.43.0：// buf:lint:ignore ID注释忽略支持向上级级联（enum 级、message 级、service 级等），并区分"忽略指令"与普通注释。
v1.52.0：buf lint/buf breaking在无 source code info 时也输出文件路径，从而在 CI 场景下也能尊重ignore/ignore_only配置。

7.2 PROTOVALIDATE 规则（v1.28.0 起）

buf lint会校验 protovalidate 规则的有效性，单条PROTOVALIDATE规则加入DEFAULT组，能力持续增强：(buf.validate.field).required语义修正（v1.28.1）、repeated校验（v1.30.1）、CEL 表达式校验（v1.64.0）、field mask 规则（v1.63.0）、oneof规则（v1.70.0）、NaN 检查于const/in/not_in/gt/gte/lt/lte（v1.70.0）、自定义规则无id/message也允许（v1.60.0）、IGNORE_IF_ZERO_VALUEpresence 检查（v1.58.0）、example 字段选项校验（v1.44.0）、预定义规则编译校验（v1.44.0）、不可执行的required规则检查（v1.65.0）。

7.3 自定义插件与 WASM 运行时

v1.42.0：支持自定义 lint/breaking 插件；v1.54.0 起protoc-gen-buf-lint/protoc-gen-buf-breaking支持本地 bufplugins。
v1.44.0：引入 Wasm 运行时，用.wasm扩展名指定自定义 lint/breaking 插件路径；v1.48.0 起buf plugin push/update/prune管理buf.lock中的插件（仅 WebAssembly check 插件）；v1.16.0 曾以BUF_ALPHA_ENABLE_WASM环境变量做过 alpha 实验（后废弃该门控）；v1.69.0 将 check 插件 WASM 内存上限提升至 1GiB。
v1.68.2：buf lint的 CEL 编译错误改用结构化错误 API，不再解析 cel-go 文本输出。

7.4 错误格式

支持junit（v1.8.0）、github-actions（v1.19.0）、config-ignore-yaml（v0.3.0，把 lint 错误直接转成可粘贴进配置的格式）、gitlab-code-quality（v1.57.0，适用于buf lint/buf breaking）、Visual Studio 格式（v0.19.0）。

八、buf curl：RPC 调试利器

buf curl（v1.12.0 引入）通过 Connect / gRPC / gRPC-Web 协议调用 RPC，能力逐版本增强：

版本	能力
v1.12.0	引入`buf curl`，支持 Connect/gRPC/gRPC-Web
v1.18.0	`--user`、`--netrc`（与 cURL 同名 flag 行为一致）；修复`--user`/`--netrc`导致 Authorization 头畸形的问题
v1.20.0	`--emit-defaults`输出 JSON 默认值；JSON 响应默认缩进
v1.26.0	对安全 https URL 支持`--http2-prior-knowledge`（配合仅支持 HTTP/2 的 gRPC 服务器 + 不支持 TLS 握手中协议协商的四层负载均衡器）
v1.28.1	支持多 schema：多个`--schema`和/或`--reflect`组合，用于解析 RPC 结果中的扩展与`google.protobuf.Any`值
v1.36.0	`--list-services`、`--list-methods`：列出 RPC schema 中的服务/方法而非发起调用
v1.38.0	`--http3`强制 HTTP/3 传输
v1.41.0	gRPC 的 HTTP/3 支持
v1.57.2 / v1.58.0	修复 HTTP/2 服务相关 bug

Unreleased 段最重要的变更：buf curl在 server reflection、gRPC 协议或双向流方法（均要求 HTTP/2）下，对httpURL 自动启用 HTTP/2 prior knowledge，--http2-prior-knowledge在这些场景不再必需。源码佐证见 curl.go 的 L578-L584：

if !isSecure && !f.HTTP2PriorKnowledge && (f.Reflect || f.Protocol == connect.ProtocolGRPC) { // Server reflection uses a bidirectional stream and the gRPC protocol // requires HTTP/2, neither of which works over HTTP 1.1. Since a // plain-text URL can only use HTTP/2 via prior knowledge, enable it // automatically rather than requiring the flag. f.HTTP2PriorKnowledge = true }

此外 curl 还支持--schema（本地 buf 模块/镜像/远程）、--reflect（服务端反射）、TLS 系列 flag（--key/--cert/--cacert/--servername/--insecure）、--user-agent、--data、--output等，flag 常量定义见 curl.go 顶部。

九、LSP：编辑器内的 buf 体验

v1.43.0：实验性 LSP 支持buf beta lsp；v1.59.0 转正为buf lsp serve（beta 命令弃用），并新增textDocument/References、基础关键字/语法/package/import 补全、workspace symbol 查询、诊断定位与格式更新修复。
能力扩展轨迹：textDocument/documentSymbol（v1.60.0）、textDocument/rename+prepareRename（v1.62.0）、折叠区间与文档链接（v1.64.0）、organize imports code action（v1.64.0，补缺失 import、删冗余 import、按字母排序）、语义 token 语法高亮（v1.64.0）、document highlight（v1.64.0）、补全选项与全限定类型引用（v1.64.0）、字段编号补全（v1.63.0）、deprecate code action（v1.65.0）、注释忽略 code action（v1.66.0）、CEL hover（v1.66.0/v1.67.0）、buf.gen.yamlcode lenses（v1.69.0，"Run buf generate"/"Check for plugin updates"）、lint/breaking ignore 路径警告（v1.69.0）、buf.yamldeps 文档链接与 code lenses（v1.68.0）、命名生成模板buf.go.gen.yaml/buf.gen.go.yaml支持（Unreleased）、依赖/well-known-type 文件间跳转与引用子集修复（v1.73.0）。
调试支持：v1.68.2 为buf lsp serve增加--debug-address。

十、BSR 注册表命令与推送能力

命令家族演变：v1.36.0 建立buf registry organization/module/label/commit稳定命令并移除 beta 版本；v1.47.0 将buf registry commit→buf registry module commit、buf registry label→buf registry module label（旧命令弃用）；v1.48.0 新增buf registry plugin {create,delete,info,update}、buf plugin push、buf registry plugin commit/label系列；v1.65.0 新增buf registry policy {commit,create,delete,info,label,settings}。
认证：buf registry login（v0.46.0）、BUF_TOKEN环境变量（v0.55.0 起，v1.13.0 支持多实例TOKEN1@BSRHOSTNAME1,TOKEN2@...）、buf registry whoami（v1.46.0）、浏览器登录流程（v1.36.0，WSL2 修复见 v1.61.0）、v1.35.0 起登录不再需要用户名。
push 增强：--create+--create-visibility（v1.19.0，v1.32.0 起默认 private）、--git-metadata（v1.32.0 自动设置 label/source-control-url/create-default-label）、--label、--source-control-url、--create-default-label（v1.32.0）、--exclude-unnamed（v1.33.0）、--draft（v1.7.0）。buf push自动携带 LICENSE/doc 文件（v1.38.0 起允许从模块目录向上查找buf.md/README.md，v1.18.0 引入 fallback 路径）。
诊断与 SDK：buf registry {module,plugin} commit的 json 输出增加source_control_url（v1.57.0）；--digest-changes-only（v1.49.0）；buf registry sdk info（v1.55.0）、buf registry sdk version（v1.32.0）；buf beta price（v1.16.0）。

十一、编译器性能与平台支持

新编译器（v1.9.0，2022-10-19）：更快、内存占用更低。CHANGELOG 给出的对比数据：生成 source code info 时快 20%、分配少 13%；不生成时快 50%、分配少 35%；大型编译过程结束时堆上存活内存不足原来一半。同时修复了 protoc 会拒绝但 buf 先前接受的若干语法问题（JSON 名冲突校验、全限定名与包名冲突、空 oneof/extend 语句、包名 ≥512 字符或 >100 个点、消息嵌套 >32 层、字段类型指向合成 map entry 消息等）。
v1.68.0：切换新编译器并支持 Editions 2024；v1.68.1 因新报告格式问题回滚，说明 buf 对编译器升级采取"先试用、可回退"的谨慎策略。
平台矩阵：arm64 发布（v0.42.0）→ Windows 支持（v0.54.0）→ Linux s390x（v1.56.0）、ppc64le 修复（v1.56.0 修正此前误发布为 x86_64 的问题；v1.54.0 正式新增 ppc64le）→ RISC-V 64-bit（v1.54.0）→ OpenBSD/FreeBSD amd64/arm64（v1.67.0）。
其他：--timeout默认值改为 0（无超时，v1.60.0）；FileAnnotation错误退出码 100（v0.41.0）；多架构 Docker 镜像（v0.41.0）；--exit-code（v1.3.0，buf format未格式化时非零退出）。

十二、兼容性承诺与迁移路径

v1.0.0-rc1 段落的表述是理解 buf 演进哲学的钥匙："我们对兼容性极其认真。我们说 v1.0 就是 v1.0——希望 buf 在 v1 上稳定十年。如果有想改变的东西，保证不破坏你是我们的责任，而不是你为我们的改变负责。" 体现在：

所有弃用均提前警告且提供迁移路径：v1.0.0 之前约两年 beta 期持续打印弃用警告；v1.0.0 一次性移除buf login、--log-level全局 flag、旧buf check *命令等。
命令迁移链完整可追溯：buf check lint→buf lint→（未再变）；buf image build→buf build；buf beta graph→buf dep graph；buf mod *→buf dep */buf config *。
规则/配置向后兼容：DEFAULTlint 分类更名STANDARD后继续工作；Editions 相关的 breaking 规则替换后旧规则仍可用；v1 与 v1beta1 配置继续被读取（新规则默认不激活，需迁移 v2 才启用）。
文件格式兼容：bin扩展名在binpb规范化后仍被接受；bingz/jsongz/targz承诺"永远继续工作"。

结语

从 CHANGELOG 可以清晰看到 buf 的演进逻辑：先跑通核心编译/校验/生成闭环，再稳定 CLI 与配置面，然后向 RPC 调试（curl）、编辑器体验（LSP）、注册表生态（BSR）与 Protobuf Editions 前沿扩展，并以"永远不破坏用户"为铁律。对使用者而言，这份文档同时是一份迁移指南、功能清单与性能基线（如 v1.9.0 编译器数据）。当前仓库处于 Unreleased 阶段（截至 v1.73.0 之后），buf curlHTTP/2 prior knowledge 自动化、buf format --stdin-filepath、远程输入去重抓取等新特性均已在源码中落地，读者可在 cmd/buf/internal/command 对应子目录（curl、format）中查看实现与测试，作为理解最新功能的起点。