# Bruno 让接口请求跟着项目一起保存在 Git 里

> Bruno 是本地优先的开源 API 客户端，把请求集合保存成项目文件，方便通过 Git 协作。本文介绍环境变量、请求调试、CLI 自动化和凭证处理，也说明免费版与付费版的选择边界。

## 关键信息

- 分类：开源项目
- 支持平台：Windows / macOS / Linux
- 收费方式：开源版免费，Pro 与 Ultimate 付费
- 开源协议：MIT
- 官网：https://www.usebruno.com/
- 源码仓库：https://github.com/usebruno/bruno
- 标签：API、开发者工具、接口测试、开源
- 收录日期：2026-11-01

后端接口改了，代码已经提交，调试时用的请求却还留在某位同事的个人工作区里。
其他人拿到项目，还要询问请求地址、认证方式和测试参数；过一段时间，团队又很难确定哪个请求集合对应哪个版本。
Bruno 提供了一种适合开发团队的整理方式：把接口请求保存为本地文件，用 Git 管理这些文件，让请求定义和项目变更一起被查看、讨论和保留。

它是面向 API 探索与测试的桌面客户端，提供 Windows、macOS 和 Linux 安装包。
开源版可以免费使用，项目仓库采用 MIT 许可，另外还有付费版本供有进阶需求的个人和团队选择[1]。

## 请求集合就是可以保存和比较的项目文件

Bruno 的集合保存在本地文件夹里，官方仓库介绍使用纯文本 Bru 格式记录请求信息，当前文档也介绍了 OpenCollection YAML 格式。
文件可以交给 Git 或其他版本控制工具管理，因此你能够把请求变更放进代码评审，也能在查阅旧版本时找到对应的接口调用方式[1][2]。

这种设计比较适合已经围绕仓库协作的团队。
例如，开发者增加了一个查询参数，可以同时修改服务代码和相关请求文件；评审者能够看到参数的变化，而不用额外索取一份导出的工作区。
团队仍需要约定文件目录、命名和提交规则，请求文件才会持续保持可用。

![Bruno 官方界面展示 GitHub REST API 请求集合、查询参数和 JSON 响应](/assets/post-images/bruno-api-client.png)

*图片来自 Bruno 官方仓库，展示 GitHub REST API 的演示请求；截图中的界面版本为 v3.0.1。*

本地保存也意味着同步方式由你选择。
Bruno 官方仓库明确说明不提供云端集合同步；团队可以利用已有的 Git 服务共享请求[1]。
发送请求时，客户端仍要连接实际的 API 地址，远程接口需要相应的网络和访问权限。
如果测试目标运行在本机，也可以在本机服务可用的情况下进行调试。

## 用环境变量处理开发环境和测试环境

同一个接口经常会有不同的服务器地址，把完整域名写进每条请求，后续修改容易遗漏。
Bruno 的环境变量可以按环境保存值，并在请求中通过 `{{变量名}}` 引用。
你可以为本地开发与测试环境分别设置 `baseUrl`，在右上角切换所用环境，复用相同的请求定义[2]。

比如团队的接口路径约定为 `/api/orders`，请求地址可以写成 `{{baseUrl}}/api/orders`。
这个路径只是组织请求的示例，实际地址、HTTP 方法和参数需要根据你的服务文档填写。
把环境差异集中在变量里，后续检查时就能区分“接口定义改了”与“测试服务器换了”。

建立第一组请求时，可以围绕一个具体业务流程组织文件：查询订单列表、查看订单详情，或者检查服务健康状态。
选择允许访问的测试环境，填写参数和认证配置，查看返回状态、响应头与响应内容。
请求名称最好写明动作和对象，文件夹则按业务模块划分，避免留下大量难以分辨的临时请求。

## 共享请求时把密钥留在共享文件之外

把集合放进 Git 之前，需要检查请求头、变量和脚本是否包含真实令牌或密码。
本地文件能够被版本控制工具提交，因此安全性取决于你保存了哪些内容、忽略了哪些文件，以及谁能访问仓库。

Bruno 的 Secret Variables 可以将环境变量标记为秘密值。
官方文档说明，这些值由客户端在本机管理，实际秘密值不会写入环境文件；环境文件保留秘密变量的名称[3]。
这样同事可以获得同样的变量结构，各自在自己的设备上填写有权限使用的凭证。

建议给团队准备一份不含秘密值的环境说明，写清变量名、用途和获取渠道。
提交前查看 Git diff，确认没有令牌、个人账号或真实客户数据混进请求示例。
自动化环境的凭证则交给 CI 平台的秘密管理机制，在运行时提供，避免把它们写在公开命令或仓库文件中。

## 请求稳定后可以交给 CLI 批量运行

Bruno CLI 可以从命令行运行集合、文件夹或单个请求，适合把已有接口检查接入自动化流程。
官方仓库给出了 npm 安装方式，以及指定环境运行集合的示例[1][4]。

在已有 Node.js 与 npm 的环境中，可使用：

```sh
npm install -g @usebruno/cli
```

进入集合所在目录后，运行整个集合：

```sh
bru run
```

如果集合已经配置名为 `Local` 的环境，可以明确指定它：

```sh
bru run --env Local
```

批量执行前，应检查集合里是否包含创建、修改或删除数据的请求，并选择专用测试环境。
需要判断业务结果时，还应给请求配置与业务有关的断言，检查响应状态和关键字段，而不仅仅查看请求是否返回了内容。

CLI 的默认运行环境还有一个值得留意的条件：官方文档说明，从 v3.0.0 起默认使用 Safe Mode。
如果集合脚本依赖外部 npm 包或文件系统访问，需要核对 Developer Mode 的权限要求，并且只对可信集合启用对应模式[4]。
这对从他人仓库拿到请求集合、准备直接批量执行的场景尤其重要。

## 免费版适合起步，付费需求要看具体功能

Bruno 定价页提供免费 Open Source，以及 Pro、Ultimate 两档付费方案。
付费方案覆盖更深入的 Git 工作流、自动化、企业集成和支持等需求，具体权益以对应版本表为准[5]。

这里要区分两件事：把本地集合文件交给 Git 管理，是本文介绍的协作方法；在 Bruno 界面里使用所有 Git 操作或企业集成功能，则需要查看当前版本的授权范围。
已经熟悉命令行 Git 的团队，可以继续使用原来的提交和评审流程。
希望在客户端内完成更多操作的团队，再对照功能表决定是否需要付费。

如果你最头疼的是“请求集合与代码版本对不上”，可以挑一个正在维护的接口模块，把可共享的请求文件放进仓库，并为环境变量写好说明。
当同事能从同一个分支找到请求、填写自己的凭证并完成调试时，Bruno 的本地文件与 Git 协作方式就有了具体的使用价值。

## 官方入口与参考资料

- [1] [Bruno 官方仓库与安装说明](https://github.com/usebruno/bruno)
- [2] [环境变量文档](https://docs.usebruno.com/variables/environment-variables)
- [3] [Secret Variables 文档](https://docs.usebruno.com/secrets-management/secret-variables)
- [4] [Bruno CLI 文档](https://docs.usebruno.com/bru-cli/overview)
- [5] [官方定价与功能对照](https://www.usebruno.com/pricing)
- [客户端下载](https://www.usebruno.com/downloads)

---

网页版：https://aronshare.com/posts/bruno-api-client/
发现线索：Bruno 官方仓库与文档 https://github.com/usebruno/bruno
来源站点：AronShare 资源库（https://aronshare.com）