全局变量环境变量临时变量模块测试数据变量

理解和掌握 Apifox 中的变量（临时、环境、模块、全局变量等）

Apifox

2025-09-04

变量其实就是给数据起个名字，然后在需要的地方用这个名字来代替具体的值。

比如你有一个经常变化的 API token，与其在每个接口中都写上具体的 token 值，不如定义一个叫 ACCESS_TOKEN 的变量，然后在接口中使用{{ACCESS_TOKEN}}。当 token 过期需要更新时，你只需要修改这个变量的值，所有使用这个变量的接口都会自动更新。

深入理解各种变量类型

Apifox 提供了多种类型的变量，每种都有其特定的使用场景。目前支持以下变量类型：团队全局变量、项目全局变量、模块变量、环境变量、测试数据变量、临时变量。

全局变量

全局变量让你能够在大范围内共享数据，Apifox 提供了两个不同类型的全局变量。

项目全局变量：它的作用范围限定在当前项目内。这种变量特别适合处理项目内接口间的数据传递。比如，你的登录接口获取到 token 后，可以将其存储到项目全局变量中，然后项目内的其他业务接口都可以使用这个 token 进行鉴权。

团队全局变量：它的作用范围更大，覆盖整个团队的所有项目。这对于跨项目的协作很有用。比如，你的团队有一个专门的用户认证项目，获取的 token 需要在其他多个业务项目中使用，这时就适合使用团队全局变量。

在权限管理上，团队全局变量有特殊的限制。普通成员只能查看和修改已有团队全局变量的本地值，不能添加、删除变量或修改变量名。只有团队管理员才能在「团队资源 -> 团队变量」页面进行完整的管理操作。

模块变量

模块变量的作用范围限定在特定模块内。如果你从 Postman 导入了 Collection，那些 Collection 变量会被导入为 Apifox 的模块变量。

模块变量适合管理某个功能模块特有的配置信息。比如，你的项目中有用户管理、订单管理、商品管理等不同模块，每个模块可能有自己特有的配置参数，这时就可以分别设置模块变量。

🦊

要使用模块变量，需要先将 Apifox 更新到最新版！

环境变量

环境变量可能是你使用最频繁的变量类型。它们让你能够轻松地在不同环境间切换，而不需要修改接口配置。

在实际工作中，你通常会有本地开发环境、测试环境、预发布环境、生产环境等多套环境。每套环境的服务器地址、数据库连接、第三方服务配置都不相同。通过设置不同的环境变量，你可以快速切换工作环境。

不过需要注意，工作环境每次只能激活一个。当你选择了某个环境后，该环境下定义的所有变量都会生效。

测试数据变量

测试数据变量有着特殊的用途：数据驱动测试。当你需要用大量不同的数据来测试同一个接口时，测试数据变量就派上用场了。

你可以准备一个 CSV 或 JSON 文件，包含多组测试数据。在自动化测试的测试场景中导入这个文件后，Apifox 会将文件中的每一行都作为一组变量值，依次执行测试。

临时变量

临时变量是最短生命周期的变量类型，它们只在单个接口或测试场景的运行期间有效。执行结束后，临时变量就消失了。

临时变量的优先级最高，这使得它们非常适合临时覆盖其他类型变量的值。比如，你的环境变量中定义了一个 user_id，但在某次特殊测试中，你需要使用不同的 user_id，这时可以设置一个同名的临时变量，而不需要修改环境变量。

变量优先级

当你定义了多个同名的不同类型变量时，Apifox 会按照优先级来决定使用哪个值。优先级从高到低是：

临时变量 > 测试数据变量 > 环境变量 > 模块变量 > 项目全局变量 > 团队全局变量

举个具体例子：假设你同时定义了三个名为 userId 的变量：

项目全局变量：userId = 1000
模块变量：userId = 2000
环境变量：userId = 3000

当你在接口中使用 {{userId}} 时，实际生效的值会是 3000（环境变量）。

如果环境变量里没有定义userId，就会使用模块变量的值 2000；如果模块变量也没有，才会使用项目全局变量的值 1000。

远程值与本地值

Apifox 中的全局、模块和环境变量有远程值和本地值两个属性，这个设计平衡了团队协作和个人隐私的需求。

远程值存储在 Apifox 的服务器上，会与团队成员同步共享。这适合存储团队共用的配置信息，比如测试环境的服务器地址、公共的接口密钥等。当团队成员更新了远程值后，其他成员同步后就能看到最新的值。

本地值只保存在你的本地设备上，不会上传到服务器，也不会被其他团队成员看到。这特别适合存储敏感信息，比如你个人的 API 密钥、密码、私有环境的配置等。

当你设置了本地值时，Apifox 会优先使用本地值。只有在本地值为空的情况下，才会使用远程值。如果你想重新使用远程值，可以点击本地值旁边的链接图标来重新绑定。

本地值存储在本地设备上，清理缓存或更换设备时会丢失。如果你使用的是 Web 版 Apifox，本地值存储在浏览器中。当你需要迁移到新设备时，可以通过导出和导入环境功能来迁移本地值。

在使用 Apifox CLI 进行自动化测试时，还有一个重要的区别：客户端运行时使用的是变量的本地值，而 CLI 运行时使用的是远程值。如果你发现客户端和 CLI 的运行结果不一致，通常就是这个原因造成的。

设置变量的多种方法

设置变量的方法有多种，选择哪种方法取决于变量值的来源和你的具体需求。

在「环境管理」中直接设置

最直接的方法是在「环境管理」界面中设置变量。点击界面右上角的环境管理按钮，你可以切换到全局变量或特定环境，然后添加变量名和对应的值。

这种方法适合设置相对固定的配置信息，比如数据库连接信息等。你可以同时设置远程值和本地值，远程值用于团队共享，本地值用于个人使用。

通过「提取变量」功能设置

很多时候，变量的值来源于接口的响应结果。比如，登录接口返回的 token，用户创建接口返回的用户 ID 等。对于这种情况，Apifox 提供了可视化的「提取变量」功能。

在接口的后置操作中，你可以添加「提取变量」操作。选择提取来源（通常是响应的 JSON 数据），然后使用 JSONPath 语法指定要提取的字段。

比如，如果响应 JSON 中有：

{
    "code": 200,
    "data": {
        "token": "123456"
    }
}

你可以用 $.data.token 这个 JSONPath 表达式来提取 token 值。

除了在后置操作中提取变量，也可以在接口的返回响应中直接设置。

在「脚本」中设置变量

对于更复杂的逻辑，你可以在前置操作或后置操作的「自定义脚本」中设置变量。Apifox 提供了一套完整的脚本 API，让你能够灵活地操作各种类型的变量。

// 设置项目中共享的全局变量
pm.globals.set('variable_key', 'variable_value');

// 设置团队中共享的全局变量（需先在“团队资源页”中定义，之后可在脚本中修改）
pm.globals.set('variable_key', 'variable_value', 'TEAM');

// 设置环境变量
pm.environment.set('variable_key', 'variable_value');

// 设置模块变量
pm.moduleVariables.set('variable_key', 'variable_value');

// 设置临时变量
pm.variables.set('variable_key', 'variable_value');

当你需要存储对象或数组时，需要先用 JSON.stringify() 转换成字符串，读取时再用 JSON.parse() 解析回来，例如：

pm.environment.set('user', JSON.stringify(userObj));

const users = JSON.parse(pm.environment.get('user'));

脚本设置变量的优势是灵活性高，你可以根据响应结果进行复杂的判断和处理。

🦊

变量的“远程值”只能在「环境管理」界面中设置，通过脚本只能设置变量的“本地值”，无法修改远程值。

将 “数据库数据” 设置为变量

Apifox 还提供了一个特殊功能：直接从数据库获取数据并设置为变量。这对于需要从数据库获取测试数据的场景很有用。

在后置操作中添加「数据库操作」，配置数据库连接信息，然后输入 SQL 查询语句，查询结果可以通过 JSONPath 语法提取到变量中。

使用变量的技巧

什么地方可以使用变量

只有在实际发送请求时，变量才会被解析成具体的值。这意味着变量可以在接口的参数、请求体、测试场景、脚本等所有涉及请求发送的地方使用。

因为 Apifox 主打一个可视化操作，所以你只要看到有 “动态值” 按钮的地方，就说明这里支持使用变量。

基本引用语法

在 Apifox 中使用变量很简单，用双大括号包裹变量名即可：{{变量名}}。这种语法可以在接口的 URL、请求头、请求参数、请求体等地方使用。

比如，在请求参数中：

在请求体中：

注意在 JSON 格式中，字符串类型的变量需要加双引号，数值类型的变量不需要加双引号。双大括号有时会触发 JSON 格式警告，但这些警告可以忽略，不影响实际执行。

当你看到“未解析的变量”提示时，不要立即认为出了问题。如果变量是通过后置操作或脚本设置的，在请求执行前确实还没有值，临时变量在执行结束后也会消失，最好的验证方法是实际发送请求看看结果。

读取变量的子元素值

有时候，你存储在变量中的不是简单的字符串或数字，而是包含多个字段的复杂数据。比如，用户信息接口返回的数据通常是一个完整的对象，包含用户 ID、姓名、邮箱等多个字段。

假设你通过脚本或提取变量功能，将这样的用户信息存储到了一个叫 user 的变量中：

{
  "id": 1001,
  "name": "张三",
  "email": "zhangsan@example.com",
  "role": "admin"
}

现在你想在其他接口中只使用这个用户的ID，不需要整个用户对象。这时你就可以用 {{user.id}} 来获取用户ID的值 1001，用 {{user.name}} 来获取姓名“张三”.

对于数组类型的数据也是类似的。假设你有一个存储多个用户的变量 users：

[
  {"id": 1001, "name": "张三"},
  {"id": 1002, "name": "李四"},
  {"id": 1003, "name": "王五"}
]

你可以用 {{users[0].name}} 来获取第一个用户的姓名“张三”，用 {{users[1].id}} 来获取第二个用户的ID 1002。

这种语法遵循 JSONPath 规范，你可以把变量名看作 JSONPath 中的根对象（相当于 $ 符号）。

在脚本中使用变量

你可以在前置操作或后置操作的「自定义脚本」中使用变量。Apifox 提供了一套完整的脚本 API，让你能够灵活地获取各种类型的变量。

// 获取项目中共享的全局变量
pm.globals.get('variable_key');

// 获取团队中共享的全局变量
pm.globals.get('variable_key', 'TEAM');

// 获取环境变量
pm.environment.get('variable_key');

// 获取模块变量
pm.moduleVariables.get('variable_key');

// 获取临时变量
pm.variables.get('variable_key');

对于存储为字符串的对象或数组，需要用 JSON.parse() 解析，例如：

const userObj = JSON.parse(pm.environment.get('user'));
console.log(userObj.name);

使用“测试数据变量”

“测试数据变量”让你能够进行数据驱动测试。准备一个包含多组测试数据的 CSV 或 JSON 文件，在自动化测试的测试场景中导入后，Apifox 会用每组数据执行一次测试。

CSV 文件的列名就是变量名，每一行都是一组变量值。测试执行时，{{变量名}} 会被替换为当前行的对应值。这样你就能用大量不同的数据来验证接口的健壮性。

使用“动态值表达式”

除了自己设置的变量，Apifox 还支持使用“动态值表达式”，也就是“动态值”，它可以根据特定规则生成随机数据。

在脚本中，你可以使用await pm.variables.replaceInAsync() 方法来处理包含动态值表达式的字符串：

const template = "Hello, {{$person.fullName}}";
const result = await pm.variables.replaceInAsync(template);
console.log(result); // 输出随机生成的姓名

动态值表达式能让你生成随机的测试数据，而不需要提前准备固定的数据集。

变量是 Apifox 中保存和复用数据的核心功能。掌握不同变量类型的用途和优先级，合理使用远程值与本地值，学会从接口响应中提取变量，这些基本技巧能让你的 API 测试工作更加高效。

立即使用 Apifox

欢迎各位用户对 Apifox 继续提出使用反馈和优化意见，我们会持续优化更新，致力于为用户提供更优秀的产品功能和更极致的使用体验！

有任何问题欢迎在Apifox 用户群与我们交流沟通！