CLI 命令选项

Apifox CLI 基础语法

在线执行：

apifox run --access-token <value> [options]

使用 Apifox 的 Access Token 运行指定的测试场景或测试场景目录，示例：

apifox run --access-token $APIFOX_ACCESS_TOKEN -t 637132 -e 358171 -d 3497013 -r html,cli --database-connection ./database-connections.json

本地执行：

apifox run <collection> [options]

指定 Apifox 测试场景的 URL 或文件路径，示例：

apifox run examples/sample.apifox-cli.json -r cli,html

参数说明

参数	描述	默认值
`--access-token <accessToken>`	设置鉴权令牌，通过此令牌结合 -t/-f 命令来指定某个测试场景/测试场景目录运行	-
`-t, --test-scenario <testScenarioId>`	指定测试场景 ID，通过 ID 运行相应的测试场景	-
`-f, --test-scenario-folder <folderId>`	指定测试场景目录 ID，通过目录 ID 运行相应的测试场景	-
`-r, --reporters [reporters]`	指定测试报告类型, 支持 cli, html, json, junit	`["cli"]`
`--out-dir <outDir>`	输出测试报告目录	`"./apifox-reports"`
`--out-file <outFile>`	输出测试报告文件名，不需要添加后缀	`"apifox-report-{当前时间戳}-0"`
`-e, --environment`	指定运行环境，本次所有测试场景使用此环境运行	-
`-n, --iteration-count <n>`	设置循环次数	-
`-d, --iteration-data <path\|testDataId>`	设置用例循环的数据 (JSON 或 CSV)	-
`--variables <path>`	设置使用指定路径中的文件内环境/全局变量，不再使用环境/全局变量远程值	-
`--env-var <key=value>`	设置环境变量，使用 key=value 格式	-
`--global-var <key=value>`	设置全局变量，使用 key=value 格式	-
`--notification <targetIds>`	运行完成后，通知指定对象。使用英文逗号添加多个通知对象 ID	-
`--notification-failed-event <targetIds>`	运行完成后，仅失败时通知指定对象。使用英文逗号添加多个通知对象 ID	-
`--external-program-path <path>`	指定 [外部程序] 的所处文件路径	命令当前执行目录
`--database-connection <path>`	指定 [数据库配置] 的所处文件路径，使用 URL 测试的时候必须指定	-
`--ignore-redirects`	阻止 Apifox 自动重定向返回 3XX 状态码的请求	-
`--silent`	阻止 Apifox CLI 输出到控制台	-
`--color <value>`	开启/关闭控制台彩色输出 (auto\|on\|off)	`"auto"`
`--delay-request [n]`	指定请求之间停顿间隔 (毫秒)	`0`
`--timeout-request [n]`	指定接口请求超时时间 (毫秒)	`0`
`--timeout-script [n]`	指定脚本预执行/后执行接口运行超时时间 (毫秒)	`0`
`-k, --insecure`	关闭 SSL 校验	-
`--ssl-client-cert-list <path>`	指定客户端证书配置路径 (JSON)	-
`--ssl-client-cert <path>`	指定客户端证书路径 (PEM)	-
`--ssl-client-key <path>`	指定客户端证书私钥路径	-
`--ssl-client-passphrase <passphrase>`	指定客户端证书密码 (for protected key)	-
`--ssl-extra-ca-certs <path>`	指定额外受信任的 CA 证书 (PEM)	-
`--upload-report`	将本次测试报告总览上传至云端，在 App 中即可查看此测试报告	-
`-b, --bigint`	兼容 bigint	`false`
`--verbose`	显示所有接口请求的详细信息	-
`--lang <language>`	设置 CLI 的语言 (zh\|en)	`"zh"`
`-h, --help`	display help for command	-

CLI 中的文件上传

在处理需要上传文件的接口时，要注意：Apifox 只保存本地文件路径，而实际文件是存在你的本地电脑或运行 CLI 的机器上的。这在不同机器上通过 CLI 运行测试时可能会出问题，因为它无法使用存储的路径访问文件。

要解决这个问题，按照下面的步骤操作：

先将需要的文件复制或上传到运行 CLI 的机器上 （如果你是在 Linux 服务器上运行，那么就上传到该宿主机）。

把该文件路径复制下来。 例如这个上传到 Linux 服务器中的图像文件路径/var/www/myapp/uploads/apifox-xiangmu.jpg：

然后在 Apifox 的自动化测试里定位到需要上传文件的接口，点击 “批量编辑” 按钮。

将上传到 CLI 机器上的 “文件路径” 填入到格式中 “参数值” 的位置即可，这样在构建时就会自动根据 “文件路径” 获取到实际文件。配置完成后，就可以通过 CLI 正确发送文件了。

除此之外，还可以把文件路径放到环境变量的 “远程值” 那里。

然后在 “批量编辑” 中通过变量的方式引用该文件路径，这样也可以在构建时通过文件路径获取到实际文件。

注意，如果你想在本地再次运行这个测试场景，需要把参数值中的文件路径改回本地机器上的路径。

CLI 中的数据库操作

当你的测试场景包含数据库操作时，因为数据库配置是保存在本地而不是云端，所以需要一些额外步骤。这意味着你不能直接在云端模式运行这些场景的 CLI。以下是处理方法：

对于包含数据库操作的测试场景，你会在命令行生成界面看到提示： “下载数据库配置文件”。

下载这个文件，把它放在你要运行 Apifox CLI 的目录下。

自动生成的命令行会包含 --database-connection 选项，直接使用这个命令行来运行测试就可以了。示例命令：

将本地 CLI 测试报告上传到云端

要把本地 CLI 测试报告上传到云端，只需在 CLI 命令末尾加上 --upload-report 参数：

在 CLI 命令中加入 --upload-report 参数：

apifox run --access-token $APIFOX_ACCESS_TOKEN -t 637132 -e 358171 -d 3497013 -r html,cli --upload-report

这个命令会运行测试，并在完成后自动把测试报告上传到云端。

查看上传的报告：

打开 Apifox 自动化测试面板中的 “测试报告”

找到 “共享” 栏目

注意：通过 CLI 上传的报告，“测试人员” 字段会显示为空。

CLI 中使用外部脚本/程序

在运行 Apifox CLI 时，可以通过在命令末尾添加路径来引用外部脚本或程序：

--external-program-path ./scripts

这个例子中，CLI 会引用 ./scripts 目录下的程序。如果没有指定层级，默认是当前 CLI 执行目录。

主要有两种管理这些外部脚本的方式：

本地路径

为了避免本地脚本管理混乱，建议：

按类别整理所有脚本文件

放在特定目录下

在 CLI 命令中指定对应的本地路径

云端代码仓库

另一种方式是：

把脚本文件放在云端代码仓库

在 CI/CD 工作流中设置拉取命令，把外部脚本拉到本地环境

在 CLI 命令中指定外部脚本的实际路径

SSL

客户端证书

Apifox CLI 支持传入客户端证书。

使用单个 SSL 客户端证书

--ssl-client-cert

指定 SSL 客户端公钥证书的路径

--ssl-client-key

指定 SSL 客户端私钥证书的路径（可选）

--ssl-client-passphrase

指定 SSL 客户端证书密码（可选）

使用 SSL 客户端证书配置文件（支持多个证书）

--ssl-client-cert-list

指定 SSL 客户端证书列表的 JSON 文件路径。例如：ssl-client-cert-list.json

ssl-client-cert-list.json

[
    {
        "name": "domain1",
        "matches": ["https://test.domain1.com/*", "https://www.domain1/*"],
        "key": {"src": "./client.domain1.key"},
        "cert": {"src": "./client.domain1.crt"},
        "passphrase": "changeme"
    },
    {
        "name": "domain2",
        "matches": ["https://domain2.com/*"],
        "key": {"src": "./client.domain2.key"},
        "cert": {"src": "./client.domain2.crt"},
        "passphrase": "changeme"
    }
]

此选项支持根据 URL 或主机名设置不同的 SSL 客户端证书。它的优先级高于 --ssl-client-cert、--ssl-client-key 和 --ssl-client-passphrase 选项。如果 URL 在列表中没有匹配项，会使用这些选项作为后备选项。

HTTP/2

CLI 可以通过 --preferred-http-version 参数配置使用特定的协议版本发送请求。

协议版本参数值：

"HTTP/2" - HTTP/2 应用层协议协商（ALPN），仅支持 HTTPS 请求

"HTTP/2-with-prior-knowledge" - 已知的 HTTP/2

"HTTP/1" - HTTP/1.1

参数支持以下配置方式：

为 HTTPS 和 HTTP 请求设置不同的协议版本：

--preferred-http-version="https=HTTP/2,http=HTTP/2-with-prior-knowledge"

为 HTTPS 和 HTTP 设置相同的协议版本：

--preferred-http-version="HTTP/1"

为 HTTPS 和 HTTP 设置 HTTP/2（不支持的值会自动忽略）：

--preferred-http-version="HTTP/2"

常见问题

如何解决 “Invalid character in header content['Authorization']” 这个错误？

如果你确定在 Apifox 客户端或网页界面运行测试用例没有问题，那么需要检查一下是否在环境中设置了变量的远程值。

Apifox CLI 基础语法#

参数说明#

CLI 中的文件上传#

CLI 中的数据库操作#

将本地 CLI 测试报告上传到云端#

CLI 中使用外部脚本/程序#

SSL#

客户端证书#

使用单个 SSL 客户端证书#

使用 SSL 客户端证书配置文件（支持多个证书）#

HTTP/2#

常见问题#

Apifox CLI 基础语法

参数说明

CLI 中的文件上传

CLI 中的数据库操作

将本地 CLI 测试报告上传到云端

CLI 中使用外部脚本/程序

SSL

客户端证书

使用单个 SSL 客户端证书

使用 SSL 客户端证书配置文件（支持多个证书）

HTTP/2

常见问题