Bruno 全局环境变量完全指南：一次配置，所有集合共用
【免费下载链接】brunoOpensource IDE For Exploring and Testing API's (lightweight alternative to Postman/Insomnia)项目地址: https://gitcode.com/GitHub_Trending/br/bruno
Bruno 是一款开源的 API 探索与测试客户端，常被当作 Postman/Insomnia 的轻量替代。它的全局环境变量让你把"哪些配置该被所有集合共享"这件事一次性做对：URL、令牌、端口写一份，处处可用。读完这篇文章，你能独立创建全局环境、用脚本动态修改变量、在 CLI 和 CI 里复用同一套配置，并绕开最常见的几个坑。
一、为什么你需要它
先想一个熟悉到头疼的场景：你维护着三个集合，分别打本地、预发、生产三套后端。每个集合里各存了一份 baseUrl 和 token。现在预发的域名换了——你翻出三处配置逐个改，还漏掉了一个，CI 红了半天才定位到。
更隐蔽的坑是认证。集合 A 登录拿到的 token，集合 B 里想用，只能手动复制粘贴。值一变，所有用到它的地方都要跟着变。
全局环境变量（Global Environment Variables）就是为解决这两类问题存在的：配置只存一份，所有集合共享，还能被脚本改写、在 CI 里注入。它和集合环境最大的区别就一句话——集合环境只对单个集合生效，全局环境跟着 Workspace 走，跨集合、跨项目都可用。
二、核心机制速览
在动手之前，先用 30 秒把全局环境变量的机制说清楚。Bruno 主界面右上角的环境选择器里，Collection 和 Global 两个标签就是这套机制的入口，请求里的{{baseUrl}}正是从全局环境取值后拼出真实 URL 的：
把 Bruno 的变量系统想成一张"合并表"，规则只有三条：
- 存成文件：每个全局环境就是 Workspace 目录下
environments/里的一个.yml文件，纯文本，可读可改，天然适合版本控制。 - 按优先级合并：请求发出前，全局、集合、环境、文件夹、请求等多层变量按固定顺序合并成一张查找表。
- 占位符取值：
{{xxx}}写进 URL、Header、Body，发请求时从表里查值替换。
一句话复述：全局环境变量是 Workspace 级的一批.yml配置，发请求时按优先级合并，{{xxx}}占位符从中取值。
机制说清了，下面上手。
三、从零到一上手：创建第一个全局环境
第 1 步：打开全局环境面板
点顶部环境选择器，切到Global标签，点创建，输入环境名（比如Local）。
第 2 步：填入键值对
在变量表格加一行：baseUrl=http://localhost:8081。值可以是数字或布尔，Bruno 会自动识别类型，不用手动声明。
第 3 步：在请求里引用
把任意请求的 URL 改成{{baseUrl}}/ping，发送。顶部环境选择器里会显示当前激活的全局环境。
第 4 步：按需再建几个环境
照同样方式建Staging、Production，切换环境 = 切下拉框，请求定义一个字都不用改。
四步走完，你已经有了一个可切换的多环境配置层。想知道这"一层"在代码里到底怎么实现的，往下拆。
四、拆开看原理：变量是怎么合并、写回和插值的
上面四步背后，代码分三段：合并、写回、插值。
1. 合并：运行时把各层变量按固定顺序展开成一张表，后写的覆盖先写的。源码在 packages/bruno-js/src/runtime/assert-runtime.js：
const context = { ...globalEnvironmentVariables, // 全局环境（最低优先级） ...collectionVariables, ...envVariables, ...folderVariables, ...requestVariables, ...oauth2CredentialVariables, ...runtimeVariables, ...processEnvVars, // 系统进程变量（最高） ...bruContext };所以"同名变量谁赢"是有明确答案的：全局环境垫底，集合、环境、文件夹、请求、OAuth 凭据、运行时、系统进程变量依次抬高。
2. 写回：脚本里用bru.setGlobalEnvVar()改全局变量，API 定义在 packages/bruno-js/src/bru.js：
script:post-response { bru.setGlobalEnvVar('global_num', 42); // 数字 bru.setGlobalEnvVar('global_bool', true); // 布尔 }脚本运行时只会把变更标记为"脏"，请求跑完后，packages/bruno-cli/src/utils/persist-variables.js 负责把变更合并回.yml文件，并根据值的类型自动补上dataType标注——这就是第 2 步"类型自动识别"的来源。
3. 插值：{{xxx}}的替换在 packages/bruno-common/src/interpolate/ 模块完成。它按正则逐个匹配占位符，支持点号取嵌套字段（如{{user.name}}），支持变量值里再嵌变量的链式替换；查不到的占位符会原样保留并触发未解析提示。
CLI 侧还有两个关键参数（见 packages/bruno-cli/src/commands/run.js）：--global-env <名称>指定使用哪个全局环境文件，--global-env-var <键=值>注入临时值。
原理清楚了，下面用三个真实任务把这些能力串起来。
五、组合实战：三个任务串起来
任务 1：一次登录，全 Workspace 共用 token
目标：集合 A 里登录拿到的 token，让集合 B、C 直接可用。
做法：在登录请求的 post-response 脚本里，把响应中的 token 写进全局变量；其他任意集合的请求头里写Authorization: Bearer {{authToken}}。
效果：一次登录，所有集合复用。token 还会落盘到环境文件，下次启动不用重新登录。
任务 2：CI 里跑测试，密钥不进仓库
目标：在 CI 中执行 Bruno CLI，使用生产全局环境，但不把任何密钥提交进仓库。
做法：
bru run request.bru --global-env Production --global-env-var TOKEN=<CI secret>效果：密钥只活在 CI 的 secret 里，通过--global-env-var临时注入。这个注入值有"防泄漏"保护——不会写进.yml文件，本地环境文件保持干净。
任务 3：环境间继承，把重复配置砍掉
目标：Staging和Base有 80% 相同的配置，不想维护两份。
做法：在Staging环境里声明extends: Base，只写差异项。
效果：Base改一处，继承方全部跟着变。这套继承关系同样落在.yml文件里，团队通过 Git 同步。
三个任务覆盖了三类典型诉求：跨集合共享、CI 安全注入、配置去重。真正落地时，坑往往藏在细节里。
六、避坑与排错清单
Q1：{{xxx}}原样发出去，没被替换？原因通常是当前激活的全局环境里没有这个键，或拼写不一致。打开环境面板核对变量名，确认右上角选中的是 Global 环境；仍不放心，就在脚本里用bru.getGlobalEnvVar('xxx')打印实际读到的值。
Q2：脚本里setGlobalEnvVar了，为什么没落盘？App 中脚本写回默认生效；但 CLI 必须显式传--global-env指定目标环境文件，不传的话，脚本修改只存在于内存，跑完即丢。
Q3：数字、布尔变量被当字符串用了？类型信息存在环境文件的dataType标注里。Bruno 写回磁盘时会自动推断并补上；手写 YAML 时确保值不带引号（42而非"42"）。
Q4：同名变量"打架"，到底谁生效？回到第二节的合并表：优先级从低到高依次是全局环境 → 集合变量 → 环境变量 → 文件夹变量 → 请求变量 → OAuth 凭据 → 运行时变量 → 系统进程变量。后合并的赢，按这个顺序查表即可。
Q5：为什么秘文变量的值不落盘？这是安全设计，不是 bug。标记secret: true的变量，值存在独立的加密存储里，.yml只留变量名；脚本通过setGlobalEnvVar写入的秘文值同样不会写进文件。好处是.yml可以放心提交进 Git。
坑排完了，最后收个尾。
七、延伸阅读
全局环境变量这套机制，一句话总结就是：文件存配置、合并定优先级、脚本可写回。想继续深入，建议按这个顺序读：
- 插值引擎：packages/bruno-common/src/interpolate/
- 脚本 API：packages/bruno-js/src/bru.js
- 变量写回逻辑：packages/bruno-cli/src/utils/persist-variables.js
- CLI 参数：packages/bruno-cli/src/commands/run.js
- 中文文档入口：docs/readme/readme_cn.md
把全局环境当配置层来用，你的 Bruno 工作流就真正搭起来了。
【免费下载链接】brunoOpensource IDE For Exploring and Testing API's (lightweight alternative to Postman/Insomnia)项目地址: https://gitcode.com/GitHub_Trending/br/bruno
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
