如何在 Apifox 中设置全局 parameter（随每个请求发送 Auth header）

假设你的项目中有 40 个接口，每个接口在调用时都需要相同的 Authorization: Bearer ... header 和 X-Api-Version header。手动为每个请求添加这两行内容不仅效率低下，而且容易出错。可能某个接口配置了 Token，而另一个接口却被遗漏了，结果你得花上一下午的时间去排查一个只在 40 个接口中的 3 个接口上出现的 401 错误。

还有更好的方法。Apifox 允许你只定义一次 parameter，并自动应用到每个请求中。在项目层级设置 header，将你的 Token 引用为变量，每个接口就会自动继承它，无需你手动修改任何一个请求。本指南将介绍实现这一目标的三个核心功能：全局 parameter、环境变量和目录范围的脚本回退。完成本指南后，你将拥有一套可运行的配置，能够为所有请求自动附加 auth header 和版本 header，并学会如何验证 header 是否已成功发送。如果你想先深入了解变量的背景知识，我们的 Apifox 变量掌握指南将是本文的极佳搭配。

让每个请求都携带标准 header 的想法并非 Apifox 独创。这与 MDN HTTP headers reference 中描述的模式相同：即随每个请求一起发送的一组少量的键值对。Apifox 的作用就是让你只需设置一次这组键值对。

什么是“全局 parameter”

Apifox 中的全局 parameter 是一种适用于整个项目而非单个接口的请求 parameter。你定义它一次，Apifox 就会自动将其附加到符合条件的请求中。

全局 parameter 涵盖四个位置，这也是该功能的核心所在：

Headers（请求 Header）：用于 Authorization 或 X-Api-Version 等内容。
Cookies（Cookie 信息）：用于会话 Cookie。
Query（URL query 参数）：用于附加到每个 URL 末尾的类似 ?api_key= 的值。
Body（请求 body parameter）：用于每个请求 body 都应携带的字段。

对于 auth-header 的使用场景，你需要选择 Headers。如果你的标准值存在于 cookie、query 字符串或 body 字段中，其他三项的工作方式也是相同的。

在开始之前，需要注意一条规则：全局 parameter 的优先级低于接口层级定义的 parameter。如果某个特定请求已经设置了自己的 Authorization header，则该接口层级的值优先，全局设置将被忽略。可以将全局 parameter 视为接口未进行自定义设置时的默认填充值，而不是强制覆盖所有内容的硬性重写。正是这种优先级机制，使得在大型项目中安全地启用全局设置成为可能。

为每个请求设置全局 header

以下是核心操作指南。目标是：在不修改任何项目中接口的前提下，将 Authorization 和 X-Api-Version 附加到项目中的每一个接口。

步骤 1：打开环境管理

全局 parameter 存在于环境管理中，你可以从页面右上角打开它。这是适用于整个项目的 parameter 的入口，Apifox 文档将其描述为随每个请求发送的数值的归宿。打开它，你将看到按位置添加 parameter 的各个区域。

步骤 2：选择 header 位置

选择 header（即请求 header 位置），因为你要添加的是一个 auth header。如果你的标准值是 cookie、query 参数或 body 字段，你只需相应地选择 Cookies、Query 或 body 即可。这四者的操作机制完全相同。

步骤 3：填写 parameter 详情

每个全局 parameter 都有一组固定的属性。为你的第一个 header 填写这些属性：

名称: Authorization
类型: parameter 类型（对于 header 值，选择 string 类型）。
默认值: Bearer {{token}}（关于 {{token}} 部分的更多信息见下文）。
描述: 简短的说明，例如 “适用于所有已认证接口的 Bearer Token。”

必填的 parameter 上还会显示 Default 字段和必填标记（星号 *）。以同样的方式添加第二行，用于版本 header：

名称: X-Api-Version
类型: string
默认值: 2024-08-01
描述: “固定用于每个请求的 API 版本。”

步骤 4：启用该 parameter

每个 parameter 右侧都有一个启用/禁用开关。打开它即可激活该 parameter。这个开关在以后非常实用：如果你需要在调试过程中临时停用某个全局 header，只需在此处将其禁用，而无需将其删除并重新输入。

步骤 5：保存

保存配置。现在，这两个 header 已成为全局配置。除非特定的接口覆盖了其中某一个，否则项目中的每个请求都将携带 Authorization 和 X-Api-Version。

步骤 6：验证它是否确实已发送

不要只是盲目相信它已经生效，我们需要进行验证。发送项目中的任意请求，然后打开响应控制台中的 实际请求（Actual Request）标签页。该标签页会展示完全真实的发送请求，其中变量已被替换为其真实值。你应该能看到列表中包含这两个 header：

GET /v1/orders/8842 HTTP/1.1
Host: api.yourservice.com
Authorization: Bearer sk_live_7f3a9c2e1b8d4056
X-Api-Version: 2024-08-01

如果这两个 header 出现在“实际请求”中，就说明它们已成功通过网络发送。这是整个配置过程中最实用的一环，因为它把“我觉得它已经应用了”变成了“我能看到它确实应用了”。

避免在 header 中直接暴露敏感信息：使用变量

请注意，上方的默认值是 Bearer {{token}}，而不是 Bearer sk_live_7f3a9c2e1b8d4056。这种双大括号语法引用了一个变量，而不是将原始 Token 硬编码到 parameter 中。Bearer 方案本身在 RFC 6750 中定义，而 MDN Authorization header 参考指南则介绍了服务端如何读取它。Apifox 文档明确指出了安全方面的问题：对于 auth Token 和 API key 等敏感数据，应使用环境变量，而不是将原始值作为明文默认值存储。变量是一个动态占位符，用于在多个请求和脚本中复用值，它能避免在 parameter 定义中暴露机密信息。

以下是设置 token 变量的方法：

点击右上角的环境图标（≡ 图标）。请注意，这与“环境管理”是不同的入口：≡ 图标是变量所在的位置。
找到 全局变量 部分。
创建一个变量，例如 token，其值为您的 bearer 密钥。
点击保存。

现在，您的全局 header 值 Bearer {{token}} 在发送时会解析为 Bearer <your-real-secret>，您可以在“实际请求”标签页中确认这一替换结果。鼠标悬停在任何地方的变量名上，都会显示其本地值和作用域，这是快速检查是否引用了正确变量的方法。

这种搭配是推荐的模式：全局 parameter 占用 header 位置，而变量负责保存密钥。我们关于 API 客户端环境和密钥管理的深入探讨，进一步介绍了如何避免在可能共享或提交的内容中泄露 Token。

根据环境切换值

当你有多个变量时，它们会变得更加有用。实际项目在开发、测试和生产阶段会请求不同的服务端，每个服务端通常需要不同的 Token。将每组变量分类到各自的环境下，然后通过 ≡ 图标旁边的 环境下拉菜单 进行切换（例如，一个示例环境可能命名为 Local Mock）。切换环境会将您的请求指向不同的一组服务端，并自动替换为该环境的变量值。您的全局 Bearer {{token}} header 保持不变；只有解析后的密钥会随着环境的变化而改变。如果您在此基础上构建 auth 流程，我们鉴权组件指南中的概念将解释 bearer、API-key 和 OAuth 定义如何映射到实际请求中。

当您只想在单个目录下使用 header 时

全局 parameter 会影响整个项目。有时这范围太广了。例如，如果只有您的 /admin 接口需要 X-Admin-Scope header，而项目的其他部分不需要携带它。

这是一个坦率的限制：Apifox 在目录设置中没有原生的“添加 header”字段。没有目录级的 header UI 可以填写。文档中所描述的替代方案是使用目录级的前置操作脚本，这样该目录下的每个请求都会继承该 header。该脚本使用与 Postman 兼容的 pm.* 脚本编写方式：

pm.request.headers.add({ key: 'X-Admin-Scope', value: 'full' });

将其添加为目录上的前置操作脚本，该目录中的每个请求都会自动带上该 header，而目录之外的请求则不会。这是一个脚本，而不是设置开关，因此请将其视为针对目录范围需求的备用方案，而不是首选路径。要了解此脚本所依赖的更广泛的脚本模型，请参阅我们的 Apifox 前置操作和后置操作脚本指南。

如何选择，以及何时使用

现在你有了三种无需编辑接口即可添加 header 的方法。请根据作用域进行选择：

全局参数 (Headers)（通过环境管理）：该 header 适用于整个项目。这是共享 auth header 或版本 header 的默认选择。
环境变量 ({{token}})：将其与全局参数配合使用，这样 header 插槽是全局的，而敏感数据则被安全地存储，并随环境的不同而切换。
目录级前置操作脚本 (pm.request.headers.add)：该 header 仅适用于单个目录。当项目范围过大时，可以使用此方法。

有几点需要注意。检查是否有重复的参数名称，以免两个全局 header 发生冲突，并确保每个参数的类型（Type）与其使用方式相匹配。此外，请记住优先级规则：设置了自身 Authorization 的接口会覆盖全局的 Authorization。当某条路由需要不同的 Token 时，这算是一个特性，但如果你忘记了该路由有自己的值，这可能会让你感到意外。这三个功能在文档中都没有任何方案限制，因此你无需购买特定档位即可使用它们。

使用 Apifox CLI 自动执行工作流

全局参数和环境不仅仅是为了 GUI 操作方便，它们也会应用到自动化运行中。当你在 Apifox 中构建保存的测试场景并从命令行运行它时，该运行会继承你通过 ID 传入的环境，因此在 GUI 中生效的同一个 Bearer {{token}} header 和 X-Api-Version 值在 CI 中也会以相同的方式进行解析。

安装 CLI (Node.js v16+) 并进行身份验证：

npm install -g apifox-cli
apifox login --with-token <YOUR_ACCESS_TOKEN>

然后针对特定环境运行保存的测试场景：

npm install -g apifox-cli
apifox login --with-token <YOUR_ACCESS_TOKEN>

-e 标志用于选择环境，因此测试场景会获取该环境的变量，包括您的 Token。-t 标志是测试场景 ID，而 -r 是 reporter（cli、html 或 junit）。这就是关联所在：只需定义一次 header 和变量，通过 CLI 运行的每个测试场景都会携带它们。有关设置和 Token 的详细信息，请参阅 Apifox CLI 安装指南；要将运行流程接入自动化，我们的 GitHub Actions 中的 Apifox CLI 教程展示了完整的流水线。

常见问题

全局 parameter 会覆盖我在特定接口上设置的 header 吗？

不会。全局 parameter 的优先级低于接口级 parameter。如果请求定义了自己的 Authorization header，则该值优先，并且在该请求中会忽略全局值。全局值作为项目默认值，在接口未设置自身值时进行填充。

我应该将实际的 Token 存储在哪里，以避免它以明文形式存在？

使用环境变量或全局变量，而不是原始的默认值。将全局 header 设置为 Bearer {{token}}，并将真实的密钥保存在通过 ≡ 环境图标创建的变量中。文档建议对敏感数据使用变量或安全方法，正是为了避免将 Token 内联存储。我们关于使用 JSONPath 提取变量的指南介绍了如何从登录响应中捕获 Token 并以相同的方式复用它。

如何确认全局 header 确实已发送？

发送任意请求，然后打开响应控制台中的 Actual Request 标签页。它会显示实际发送的请求，其中 {{token}} 和其他变量已被替换为它们的值。如果你的 header 出现在那里，说明它已经通过网络发送出去了。

我可以只为单个目录添加默认 header，而不是整个项目吗？

可以，但不能通过设置字段来完成，因为 Apifox 没有原生的目录 header UI。使用 pm.request.headers.add({ key, value }) 在目录上添加一个前置脚本，这样该目录中的每个请求都会继承该 header，而项目的其他部分则不会。

使用全局 parameter 或环境变量需要付费计划吗？

这些功能的文档没有列出任何版本限制。全局 parameter、环境变量和目录级前置脚本的文档均未提及免费与付费的限制。

总结

在 Apifox 中为每个请求设置 header 是一项一次性的工作：在环境管理中将 header 定义为全局 parameter，将密钥引用为 {{token}} 变量以避免明文泄露，并通过 Actual Request 标签页确认其已发送。当您只需要在单个目录上使用 header 时，可以使用前置脚本作为替代方案。要在您自己的项目中体验，请下载 Apifox 并设置您的第一个全局 header。它是免费的，无需信用卡。