Postman 使用 Runner 读取 CSV 参数批量请求的步骤

如果一组接口只是参数不同，逐个修改请求再点击 Send 很快就会失去可重复性。更稳妥的做法是让 CSV 的每一行代表一次迭代，把列名映射为请求变量，再交给 Collection Runner 批量执行。本文只讲这一条路径：准备 CSV、绑定变量、选择数据文件、运行和确认结果。

官方文档：https://learning.postman.com/docs/running-collections/working-with-data-files/

核心关系是：CSV 第一行的表头决定变量名，后面的每一行决定一次 iteration。请求里写成 {{email}}，Runner 就会在对应迭代中替换成这一行的 email 值。

一、先把 CSV 整理成“一行一次请求”

打开文本编辑器，新建一个 UTF-8 编码的 CSV。第一行只放字段名，后面每行代表一次请求输入。下面的示例准备了三个用户订单：

email,order_id,remark
alice@example.com,ORD-1001,首单
bob@example.com,ORD-1002,补发
carol@example.com,ORD-1003,人工复核

CSV 是数据文件，不支持像 Go、JavaScript 那样的注释语法，所以字段含义要放在代码块外说明。表头 email、order_id 和 remark 会成为 Runner 能读取的变量名；不要在表头前后加入空格，也不要把中文说明写进第一行。

保存后先做三个肉眼检查：列数是否一致、值中是否有未处理的英文逗号、文件是否带有正确的 UTF-8 编码。如果某个值本身包含逗号，应按 CSV 规则用双引号包住，例如 "华东,一组"。

二、在请求中引用 CSV 表头

在 Postman 左侧打开目标 collection，进入要重复执行的请求。把 URL、Params、Headers 或 Body 中需要随每行数据变化的部分写成双花括号变量。比如请求体可以是：

{
  "email": "{{email}}",
  "order_id": "{{order_id}}",
  "remark": "{{remark}}"
}

这是严格 JSON，因此不能在对象内部添加注释；三个字段的作用分别是收件地址、订单编号和备注。请求中的固定字段继续保留固定值，只有需要被 CSV 驱动的字段才写变量。这样既能减少数据文件的列数，也能避免把鉴权、接口地址等不应变化的设置放入 CSV。

点击请求右上角的 Send 做一次单条占位检查时，如果没有绑定 Runner 数据文件，变量可能显示为未解析状态，这是正常的。真正的 CSV 替换发生在 Runner 的迭代上下文中。

三、从 Collection Runner 载入 CSV

在 Postman 顶部选择 Runner，再选择包含目标请求的 collection。若只想运行一个请求，可以在运行器中展开 collection 后缩小到对应文件夹或请求。把右侧运行设置滚动到 Data file 区域，选择 Select file，加载刚才保存的 users.csv。

选择后重点看预览区域，而不是只看文件名：

• 列名应出现 email、order_id、remark。
• 预览的第一条数据应对应 CSV 的第一条数据行，而不是把表头当成值。
• 如果第一列名称出现乱码或多余字符，先重新用 UTF-8 保存文件，再重新选择。

只有预览列名和请求中的变量名能够一一对应时，才继续配置运行次数。

四、按数据行运行并确认迭代状态

数据文件绑定后，Runner 会以 CSV 数据行作为迭代来源。将迭代次数保持为数据文件行数对应的数量；不要为了“多跑几次”手动填入大于数据行数的值，否则后续迭代没有新的输入，排查时容易把空值误认为接口问题。确认环境、请求顺序和数据文件后，点击运行按钮。

成功启动后，先看运行概览中的 iteration 计数，再点开一条请求查看实际展开值。下面的界面说明图展示了一个完成三次迭代后的结果状态：

每次迭代至少确认三件事：请求详情里的 email 和 order_id 已经从变量变成当前行的具体值；运行计数与数据行数一致；响应状态和响应体符合这个请求本身的预期。不要只凭总的 200 状态判断数据绑定正确，因为接口可能接受空字段。

五、变量没有替换时按这条顺序排查

1. 先对表头，不要先改环境变量

确认 CSV 的表头与请求中的变量名完全一致，包括大小写和下划线。order_id、orderId 与 order_id 是三个不同的名字。修改 CSV 后，要在 Runner 中重新选择文件，避免继续使用旧的预览。

2. 再看文件是否真的绑定到当前运行

同一个 collection 可以从不同入口启动。重新打开 Runner，确认 Data file 区域仍显示当前文件，并能看到实际列名；如果只是打开请求窗口单独发送，CSV 行上下文不会自动注入。

3. 最后区分 CSV 变量和环境变量

环境变量适合保存固定的服务地址或测试环境配置，CSV 变量适合保存每次迭代不同的业务数据。不要把同一个名称同时放在环境和 CSV 中来“兜底”，否则读者很难从请求详情判断最终值来自哪一层。为批量测试使用专门的字段名，例如 order_id，并在单条请求中保持同样的写法。

常见问题

CSV 是否必须有表头？建议保留。Runner 需要通过表头把列映射为变量；没有稳定表头时，变量含义和排错成本都会变差。

为什么文件有三行数据，运行却不是三次？第一行通常是表头，不算数据行。还要检查是否在 Runner 中手动修改了迭代次数，以及 CSV 是否有空行。

请求返回成功但业务数据不对怎么办？先打开某一次迭代的请求详情，核对实际展开的 email、order_id 和请求体；如果展开值正确，再把问题收窄到接口响应或业务校验，而不是继续修改 CSV。

最后确认清单

完成后可以用这份短清单收尾：CSV 第一行是稳定表头；每个数据行代表一次请求；请求变量名与表头逐字一致；Runner 的 Data file 有文件名和列预览；迭代数与数据行数匹配；至少抽查一条请求详情中的实际展开值。满足这六项，Postman 就能把 CSV 参数稳定地交给 Runner 批量发送。