Insomnia 怎样为接口请求切换环境变量

同一组接口在开发、测试和生产环境里往往只差一个域名或一组凭据。Insomnia 的做法是把变量放进环境，再让请求引用变量；切换子环境后，同一请求就能使用另一组值，不需要反复改 URL。

官方地址：https://developer.konghq.com/insomnia/

本文只讲 Insomnia 的环境层级、子环境切换、请求引用和未生效排查。示例使用 api.example.test 与占位 Token，不代表真实服务，也不会发送真实请求。

最稳妥的组织方式是：基础环境只放通用默认值，开发或测试差异放在子环境；请求只引用变量名，不把环境地址写死。

先理解 Insomnia 的环境入口

打开一个项目后，在侧栏进入 Environments。Insomnia 的环境可以按作用范围分成全局环境、集合环境和文件夹环境；同一集合里最常用的是“集合基础环境 + 多个子环境”。

可以把它理解成一条从通用到具体的配置链：

• Global Environment：多个集合都可能复用的默认值。
• Collection Base Environment：当前集合通用的基础 URL、API 前缀等。
• Sub-environment：开发、Staging 或 Production 等差异值，通常继承基础环境，只覆盖需要变化的字段。
• Folder Environment：只对某个文件夹内的请求生效，适合局部测试场景。

如果同名变量在多层都存在，优先级会影响最终值。写文章时不需要记住所有层级，但排查时要按“文件夹环境、选中的集合子环境、集合基础环境、选中的全局子环境、全局基础环境”的顺序检查。

在 Base Environment 保存通用变量

先选中集合的基础环境，保存不会随环境切换而变化的默认值。例如把 API 的根地址拆成 base_url，把路径前缀拆成 api_prefix。值使用占位地址即可，真实凭据不要直接写进教程或提交到仓库。

{
  "base_url": "https://api.example.test",
  "api_prefix": "/v1",
  "request_timeout_ms": 5000
}

上面的 JSON 是环境编辑器中的数据，不要给严格 JSON 加注释；字段含义可以在代码块外说明。base_url 负责主机地址，api_prefix 负责公共路径，超时时间则是可选的普通配置。

如果你只需要在一个集合里使用这些值，优先放在集合基础环境，避免全局环境变得过于庞大。只有多个集合都确实共享的变量，才放到全局层。

创建 Development 和 Staging 子环境

在基础环境旁边创建子环境，例如 Development 和 Staging。子环境会继承父级变量，因此只填写不同的字段即可。开发环境可以覆盖本机服务地址，测试环境则覆盖到测试域名。

{
  "base_url": "http://127.0.0.1:8080",
  "api_prefix": "/v1"
}

再创建一个 Staging 子环境：

{
  "base_url": "https://staging.example.test"
}

Staging 没有重复写 api_prefix，会继续继承基础环境的 /v1。这比在每个环境里复制完整 JSON 更不容易出现路径漂移。

环境切换只改变当前请求解析变量时采用的值，不会自动修改请求本身，也不会把不同环境的响应混在一起。切换后先看当前环境指示，再看请求 URL 的解析预览。

让请求引用环境变量

在请求 URL、请求头或请求体的文本输入中，输入变量名并从自动提示中选择环境变量。示例 URL 可以写成：

{{ base_url }}{{ api_prefix }}/users

请求头中的占位值也可以引用变量：

Authorization: Bearer {{ token }}

为了让请求在没有 Token 时也容易排查，可以先用非敏感占位值说明结构：

{
  "page": 1,
  "page_size": 20,
  "client": "insomnia-demo"
}

这里的请求体 JSON 必须保持合法格式；变量的实际值由 Insomnia 在请求运行时解析。若变量名拼错，优先检查自动提示是否能找到同名字段，不要先怀疑接口服务。

切换环境后查看解析结果

选择 Development 时，URL 应该解析到本机占位地址；选择 Staging 后，URL 应该改为测试地址。切换完成后，观察三个位置：

1. 环境选择器是否显示了目标子环境。
2. 请求 URL 的变量是否能被解析为一个完整地址。
3. 变量查看或来源提示是否指向选中的集合子环境，而不是旧的基础环境。

如果使用的是 Mac，可以用环境编辑器快捷键打开和切换环境；但快捷键只负责进入编辑器，真正决定请求值的仍然是当前选择与变量层级。

用一个小脚本理解变量的使用边界

如果需要在前置脚本中读取或更新变量，先区分“环境变量”和“临时变量”。下面的示例只展示变量名和生命周期，使用的是假值：

// 读取当前环境中的 base_url，并把本次运行的标记写入临时变量
const baseURL = insomnia.environment.get('base_url');
if (!baseURL) {
  throw new Error('缺少 base_url，请先选择正确的环境');
}

// 临时变量只服务于当前请求链，不把调试标记写回共享环境
insomnia.variables.localVars.set('request_label', 'insomnia-demo');

脚本的重点是边界：共享配置应放在环境里，临时计算结果则放到本地变量；不要为了临时调试把真实 Token 写进集合基础环境或提交到 Git。

环境切换不生效时按层级排查

出现“切换了但 URL 没变”时，可以按下面顺序处理：

1. 确认选中的对象：当前选择的是子环境，不是仍停留在 Base Environment。
2. 检查变量拼写：base_url、api_prefix 等名称要完全一致，大小写和下划线都不能凭感觉修改。
3. 检查更高优先级覆盖：文件夹环境可能覆盖集合子环境；删除测试用的同名临时变量后再看解析值。
4. 检查是否只覆盖了部分字段：子环境只写差异值是正常的，未覆盖的字段仍然来自父级。
5. 检查敏感值的存储方式：需要加密的值使用 Secret；只想避免界面直接显示时，理解 Confidential 的明文存储边界，不把它当成加密。

排查时可以先把请求 URL 缩短成 {{ base_url }}/health 这样的占位路径，确认主机切换正常后，再恢复完整路径。这样能把“环境问题”和“接口路径问题”分开。

常见误区

• 每个环境都复制一整份变量：容易出现父级修改后子环境仍保留旧值，优先采用继承加覆盖。
• 把真实 Token 放进普通 JSON：普通环境导出或同步时可能暴露值，敏感信息应使用合适的 Secret 机制。
• 把环境切换当成请求重写：切换只改变变量解析，固定写死的 URL 不会自动变化。
• 看到空值就连续发送请求：先看变量来源和当前环境，避免用错误地址反复打接口。

小结

Insomnia 环境变量的关键不是多建几个环境，而是让层级职责清楚：基础环境保存通用值，Development 或 Staging 子环境只覆盖差异，接口请求统一引用变量。切换后看当前环境、解析后的 URL 和变量来源；如果仍不生效，再从文件夹到全局逐层检查覆盖关系。

相关问题

问：子环境必须把所有变量重新写一遍吗？
答：不需要。子环境通常继承基础环境，只写开发、测试或生产中发生变化的字段即可。

问：为什么请求 URL 里变量没有被替换？
答：先确认当前选择了正确环境，再检查变量名拼写和是否存在更高优先级的文件夹变量覆盖。

问：Confidential 变量等同于加密吗？
答：不等同。它主要减少界面预览中的意外暴露；需要加密保存的敏感值应使用 Secret，并理解导出与同步边界。