Bruno 4.3 上手：接口集合存进 Git 仓库，离线调试到 CLI 自动化

Bruno 是一个开源的 API 客户端，把每个接口请求保存成仓库里的纯文本文件，因此能像代码一样提交、评审和回滚。它不需要注册账号，默认不把请求内容同步到云端，另外提供命令行工具，用于在持续集成里跑接口测试。它适合希望接口数据留在自己磁盘上的开发与测试团队。

Bruno 是什么：接口集合变成仓库里的纯文本

常见客户端把集合放在厂商云端，换工具或团队扩容时往往要重新导入、重新配置权限。Bruno 的存储反过来：一个集合就是本地的一个文件夹，集合配置、请求、环境变量全是纯文本。用 Git 就能完成共享与版本管理。

官方文档把它的定位写成 Git-friendly、offline-first。日常使用不需要账号，邮箱只在购买许可、签发 license 时用到。

项目以 MIT 许可开源，代码托管在 GitHub 的 usebruno/bruno。截至 2026 年 11 月 1 日，仓库显示 47,972 个 star、3,064 个 fork，最近一次发布是 10 月 22 日的 v4.3.0。

• 请求以文件保存，一条请求一个文件，便于单独查看差异。
• 环境变量同样落在文件里，测试、预发、生产各一份。
• YAML 格式下集合根文件叫 opencollection.yml，旧格式是 bruno.json。
• 桌面端覆盖 Windows、macOS、Linux 三个平台。

除了桌面端，它还有命令行工具、Docker 镜像和 VS Code 扩展三种入口，文档里另外单列了 Mock Server 与 API Docs 两章。形态多但不绑账号，这是它和同类工具拉开距离的地方。

安装与起步：桌面端、包管理器与命令行

官网下载页提供 Windows x64 与 Arm64 的 EXE、MSI 和 ZIP 便携包，也有 macOS 与 Linux 的构建，页面标注版本 4.3.0。桌面端与命令行工具分开分发，只做自动化的机器装 CLI 即可。

桌面端启动后会建立一个默认工作区，之后按项目新建集合，格式可选 YAML 或 .bru。写完请求补上环境变量，把这个文件夹初始化成 Git 仓库，协作方式就定下来了。

集合在 Git 仓库里怎么组织

v4 推荐使用 OpenCollection YAML：集合根目录放 opencollection.yml，请求写成 .yml，环境文件放在 environments/ 下，子目录里再用 folder.yml 描述分组。

旧的 .bru 标记语言仍在支持范围内，但已被标记为弃用。官方博客说明会继续支持至少十二个月，并在过渡期保持两种格式的功能对齐，迁移节奏由团队自己决定。

纯文本带来的直接好处是评审。接口改动和调用方改动会出现在同一个 PR 里，评审者看到的是字段级差异，而不是一整块导出的二进制或长 JSON。

YAML 还能交给 yamllint、prettier 这类现成工具检查，编辑器自带语法高亮，几乎不用额外装插件。

已经有 .bru 集合的团队不必一次改完。两种格式可以在同一个仓库里共存，新请求用 YAML，老请求保留原样，按模块逐步替换。

用 CLI 把接口测试接进流水线

CLI 的入口命令是 bru。在集合目录执行 bru run，会按顺序跑完请求并打印一张执行摘要表，包含通过数量与失败项。

常用参数不多：--env 指定环境，--tests-only 只跑带测试或断言的请求，--env-var 在运行时覆盖变量，这样密钥不必写进文件。

• 报告：--reporter-html、--reporter-json、--reporter-junit，其中 JUnit 结果能直接喂给 CI 的测试面板。
• 数据驱动：--csv-file-path 或 --json-file-path，每一行数据执行一次请求。
• 容器：官方镜像 usebruno/cli，Alpine 变体基于 node:22-alpine，体积约 141 MB，挂载目录固定为 /bruno。

只装 CLI 的机器不需要图形界面，集合跟着代码仓库一起拉下来就能跑。执行时机要自己安排，把它放在合并请求或部署前的步骤里比较自然。如果顺带整理本地命令行，可以参考终端命令行工具清单里的几款工具搭配使用。

与 Postman、Insomnia 对照：差异与局限

一处局限在 Git 图形界面。免费版覆盖初始化、查看差异、检查更新、拉取和克隆；提交、推送、分支、合并冲突处理需要 Pro 或 Ultimate 版本。用命令行 git 可以绕开，但界面里的按钮会被拦住。

另一处是协作模型。它没有厂商托管的账号体系，多人共享依赖仓库权限，对不写代码的产品、运营同事不算友好。云端 Mock 与监控面板这类一体化能力，也不在它的范围内。

还有升级成本。据 v4.0.0 发布说明，这一版带有破坏性变更。secret 配置从 secrets.json 迁到环境文件，CLI 不会自动迁移，需要先用桌面端打开一次集合。

脚本修改变量默认写入磁盘，涉及密钥时要显式关闭持久化。混版本团队需要协调升级，否则新格式集合在旧版本里可能打不开。

付费档位公开在 定价页：开源版 0 美元，Pro 每用户每月 6 美元、按年计费，Ultimate 11 美元。只做本地调试的个人，开源版已经够用。

迁移方面它提供了转换器，可以从 Postman、Insomnia、OpenAPI 与 WSDL 导入集合。复杂脚本与鉴权流程在转换后仍要人工核对一遍，不能指望一次到位。

适合谁用，怎么开始

如果团队把接口测试当成代码的一部分，愿意在 PR 里评审请求变更，它的组织方式能省掉不少导出导入。需要离线环境，或者公司政策不允许把接口数据放到第三方云端的场景，同样是它的适用范围。

反过来，如果协作主要发生在非技术同事之间，或者重度依赖云端 Mock、监控与共享工作区，切换成本可能高于收益。

1. 先在一个仓库里建集合，选 YAML 格式，写三条最能代表业务的请求。
2. 把环境变量分成公开与私密两份，私密那份加进 .gitignore。
3. 装 CLI，执行 bru run --env local，确认断言能通过。
4. 把这一步写进 CI，先只在合并请求时执行，当冒烟测试用。

如果这条链路后面还要接模型调用，可以看LiteLLM 把多家大模型 API 收成一个兼容入口的做法。MCP 协议入门那篇讲的是工具与模型之间怎么约定调用，和接口集合的组织思路有相通之处。两者配合使用，能把调试与自动化放在同一套工程规范里。