Mockoon CLI 完全指南:用 @mockoon/cli 在任意环境部署 Mock API
Mockoon CLI 完全指南:用 @mockoon/cli 在任意环境部署 Mock API
Mockoon 官方 CLI(@mockoon/cli)是一个轻量级的 NPM 包,用于将你的 Mock API 部署到任何环境:只需提供一个 Mockoon 数据文件或 OpenAPI 规范文件(JSON/YAML),即可在本地、CI/CD 流水线、Docker 容器中一键启动 Mock 服务。CLI 与桌面应用共享同一套核心能力——模板系统、代理模式、路由响应规则 等,读完本文你将掌握从安装、启动、参数调优到 Docker 化、OpenAPI 导入导出、Admin API 调用乃至 MCP AI 集成的完整实战方案。
安装与基本使用
全局安装 CLI:
$ npm install -g @mockoon/cli
安装完成后,通过 mockoon-cli 命令调用:
$ mockoon-cli COMMAND
CLI 基于 oclif,支持的命令包括:start、dockerize、import、export、validate、mcp 和 help。当前仓库中 CLI 版本为 9.9.0(见 packages/cli/package.json),要求 Node.js >= 18,官方已测试 Node.js 18、20、22 和 24 版本。
💡 需要了解 Mockoon 各应用版本更新内容,可查阅官方 changelogs;Mockoon CLI 使用 MIT 许可证开源发布。
使用 Mockoon 环境文件运行 Mock API
CLI 可以导入并迁移旧版本 Mockoon 的数据文件,但不会修改你提供的原文件,只迁移一份副本。如果你用更新版本的桌面应用创建了 Mock,请先升级 CLI:npm install -g @mockoon/cli。
使用 start 命令一步启动:
$ mockoon-cli start --data ~/path/to/your-environment-file.json
从桌面应用定位环境文件:右键点击环境,在上下文菜单中选择 "Show in folder"。
也可以直接提供 URL 加载远程环境文件:
$ mockoon-cli start --data https://domain.com/your-environment-file.json
运行 Mockoon Cloud 环境
自 v9.5.0 起,可以通过 cloud:// 协议直接运行云端托管的 Mockoon 环境:
$ mockoon-cli start --data cloud://{UUID} --token {TOKEN}
其中 {UUID} 是环境的 UUID,{TOKEN} 是 Mockoon Cloud 的 access token。桌面应用会在环境下拉菜单中给出在你的服务器上运行该 Mock 所需的命令与说明。该命令主要为既有 Cloud 客户保留,新团队部署建议使用 Mockoon Pro 的自托管方案。
从源码看,cloud:// 的解析逻辑位于 packages/cli/src/libs/data.ts:loadFile 检测到 cloud:// 前缀后,会向 Config.cloudApiUrl(生产环境为 https://api.mockoon.com/environments,见 packages/cli/src/config.ts)发起携带 Authorization: Bearer <token> 的请求拉取环境;token 可通过 --token 标志或 MOCKOON_CLOUD_TOKEN 环境变量提供(见 packages/cli/src/commands/start.ts)。
使用 OpenAPI 规范文件运行 Mock API
另一种方式是直接把 OpenAPI 规范文件作为 --data 参数传入,Mockoon 支持 JSON 与 YAML 两种格式,以及 OpenAPI 2.0.0 和 3.0.0 版本:
$ mockoon-cli start --data ~/path/to/your-opeanapi-file.yaml
或提供远程 URL:
$ mockoon-cli start --data https://domain.com/your-opeanapi-file.yaml
⚠️ 注意:OpenAPI 规范与 Mockoon 的完整功能之间并非一一对应。如果要用 CLI 运行具备全部特性(模板、规则等)的 Mock API,必须直接使用 Mockoon 数据文件,否则可能丢失部分 Mock 行为。
从实现上看,packages/cli/src/libs/data.ts 中的 parseDataFile 会先尝试用 OpenApiConverter(来自 @mockoon/commons)把输入转换为 Mockoon 环境;只有 OpenAPI 解析失败且文件不是 YAML 时,才按 JSON Mockoon 数据文件解析。若文件是 .yml/.yaml 且无法解析为合法 OpenAPI,会直接报错。
start 命令详解
start 以前台进程方式启动一个或多个 Mock API。Mock 默认运行在数据文件中指定的端口和主机名上,可用 --port 和 --hostname 覆盖。--data、--port、--hostname、--public-base-url 均支持多值,一次启动多个 Mock API(见下方示例)。
💡 要以后台进程方式运行 CLI,在命令末尾加
&:mockoon-cli start -d ./data-file.json &。
用法:$ mockoon-cli start
选项:
| Flag | 说明 |
|---|---|
| -d, --data | [必需] 指向你的 Mockoon 文件的路径或 URL,支持 cloud:// 云 URL |
| -p, --port | 覆盖环境端口 |
| -l, --hostname | 覆盖默认监听主机名 |
| -c, --faker-locale | Faker 区域设置(如 'en'、'en_GB',支持的区域见下文) |
| -s, --faker-seed | Faker.js 种子数字(如 1234) |
| -t, --log-transaction | 记录完整 HTTP 事务(请求和响应) |
| -X, --disable-log-to-file | 禁用写入文件日志 |
| -e, --disable-routes | 按 UUID、路由路径中的关键字(不带前导斜杠)或文件夹名中的关键字禁用路由;用 '*' 禁用所有路由 |
| -r, --repair | 数据文件太旧或无效时,无需提示直接迁移/修复 |
| -x, --env-vars-prefix | 环境变量前缀(默认:'MOCKOON_') |
| -w, --watch | 监听本地数据文件变更并自动重启服务器(watch 使用轮询,见 --polling-interval) |
| --polling-interval | 本地文件监听轮询间隔(毫秒,默认 2000) |
| --disable-admin-api | 禁用默认开启的 Admin API |
| --admin-api-token | Admin API bearer token。提供一次即可对所有环境复用,或多次(或逗号分隔)为每个环境设置一个 token。也可通过 MOCKOON_ADMIN_API_TOKEN 设置 |
| --admin-api-cors-origin | Admin API 允许的 CORS 来源(如 'https://app.example.com')。可多次提供或逗号分隔。用 '*' 显式开启通配 CORS。省略时不发送任何 CORS 头。也可通过 MOCKOON_ADMIN_API_CORS_ORIGIN 设置 |
| --disable-tls | 为所有环境禁用 TLS(TLS 配置属于环境配置的一部分) |
| --max-transaction-logs | 内存中保留、供 Admin API 检索的事务日志最大数量(默认 100) |
| --max-request-body-size | 所有内容类型的最大请求体大小(默认 100MB)。设为 0 禁用限制。可用原始字节数或人类可读字符串(如 104857600、100MB、10 GB、1.5kb) |
| --enable-random-latency | 在 0 与指定值之间随机化全局与响应延迟(默认 false) |
| --proxy | 覆盖环境代理设置(选项:'enabled' 或 'disabled') |
| --public-base-url | 用于解析相对回调 URL及 baseUrl 模板助手的公开基础 URL(如 https://api.example.com 或 http://localhost:3000)。必须包含协议,非标准端口也需包含 |
| -k, --token | 获取 legacy Mockoon Cloud 环境所需的访问 token |
| --max-callback-depth | 带回调的路由响应的最大调用栈深度(默认 100) |
| --enable-route-metadata-headers | 为响应添加路由元数据头(UUID 与响应元数据)(默认 false) |
| --disable-external-refs | 加载 OpenAPI 规范时禁用获取外部 HTTP/HTTPS $ref 引用(默认 false) |
| -h, --help | 显示 CLI 帮助 |
示例:
$ mockoon-cli start --data ~/data.json
$ mockoon-cli start --data ~/data.json --watch
$ mockoon-cli start --data ~/data1.json ~/data2.json --port 3000 3001 --hostname 127.0.0.1 192.168.1.1
$ mockoon-cli start --data https://file-server/data.json
$ mockoon-cli start --data ~/data.json --log-transaction
$ mockoon-cli start --data ~/data.json --disable-routes route1 route2 folder1
$ mockoon-cli start --data ~/data.json --disable-routes=*
$ mockoon-cli start --data ~/data.json --disable-routes "*"
$ mockoon-cli start --data ~/data.json --public-base-url https://api.example.com
$ mockoon-cli start --data ~/data.json --max-request-body-size 100MB
$ mockoon-cli start --data cloud://def01727-aeb7-4cf1-9172-e0c38f22b224 --token mkn_sk_1234567890abcdef
底层实现:从数据文件到 Mock 服务器
从源码结构看,packages/cli/src/commands/start.ts 中的 run() 会遍历每个 --data 条目:先调用 parseDataFile 完成加载、OpenAPI 转换或 JSON 解析、迁移与校验(迁移逻辑见 packages/commons/src/libs/migrations.ts),随后用 MockoonServer 创建服务器实例,通过 listenServerEvents 订阅日志事件,并监听 PORT_ALREADY_USED、PORT_INVALID、HOSTNAME_UNAVAILABLE、CERT_FILE_NOT_FOUND 等致命错误(以退出码 2 终止进程)。启用 --watch 时,使用 chokidar 以 usePolling: true 轮询监听文件变化,检测到变更后执行 server.stop() → server.updateEnvironment() → server.start() 热重启。
Admin API
每个运行中的 Mock API 默认开启 Admin API,访问路径为 /mockoon-admin/。它允许你与运行中的 Mock API 交互、检索日志等,可用 --disable-admin-api 关闭。
启用 Admin API 时,bearer 认证始终开启:
- 用
--admin-api-token(或MOCKOON_ADMIN_API_TOKEN)提供 token;若未提供,启动时会自动生成安全 token 并打印到日志中。 - 提供单个 token 可在所有环境间复用;同时启动多个环境时,可为每个环境提供各自的 token。
- 通过
Authorization: Bearer <token>请求头发送 token。
默认情况下 Admin API 不发送 CORS 头,会阻止浏览器跨域请求。若要允许特定来源(如部署在其他域名的前端),使用 --admin-api-cors-origin(或 MOCKOON_ADMIN_API_CORS_ORIGIN):
$ mockoon-cli start --data ~/data.json --admin-api-cors-origin https://app.example.com
$ mockoon-cli start --data ~/data.json --admin-api-cors-origin https://app.example.com https://admin.example.com
只有请求的 Origin 头匹配允许值时才会收到 CORS 头。使用 --admin-api-cors-origin "*" 显式开启通配 CORS(不建议用于暴露在公网的实例)。
Admin API 返回的事务日志(GET /mockoon-admin/logs 及 SSE 事件流)会脱敏已知敏感请求头(authorization、proxy-authorization、cookie、set-cookie、x-api-key、api-key、x-auth-token)。对于 authorization / proxy-authorization,会保留认证方案(如 Bearer [REDACTED])。请求与响应体不做修改。
从源码看,Admin API 端点实现在 packages/commons-server/src/libs/server/admin-api.ts,CORS 校验、SSE 事件流、日志检索均在该文件中实现。
Faker.js 选项
- 区域(Locale):通过
--faker-locale设置 Faker.js 区域。未提供时使用默认区域en。当前仓库中 Mockoon commons 库支持的区域列表定义在 packages/commons/src/constants/faker.constants.ts,包含af_ZA、ar、az、cs_CZ、da、de、de_AT、de_CH、dv、el、en、en_AU、en_AU_ocker、en_BORK、en_CA、en_GB、en_GH、en_IE、en_IN、en_NG、en_US、en_ZA、eo、es、es_MX、fa、fi、fr、fr_BE、fr_CA、fr_CH、fr_LU、he、hr、hu、hy、id_ID、it、ja、ka_GE、ko、lv、mk、nb_NO、ne、nl、nl_BE、pl、pt_BR、pt_PT、ro、ro_MD、ru、sk、sr_RS_latin、sv、tr、uk、ur、vi、yo_NG、zh_CN、zh_TW、zu_ZA等 60+ 区域(部分区域可能尚未在 Mockoon 中完全实现)。start 命令会校验传入的区域是否在该列表内,否则报错退出。 - 种子(Seed):通过
--faker-seed设置种子数字。未提供时不使用种子;提供后可以生成可重复的假数据序列——注意播种后生成的不是恒定值,而是可预测的序列。
自定义环境变量前缀
可以在路由响应中用 {{getEnvVar 'VARIABLE_NAME'}} 模板助手访问环境变量。默认只有以 MOCKOON_ 前缀开头的环境变量可用,例如 MOCKOON_MY_VARIABLE。
用 --env-vars-prefix 自定义前缀。例如设置 --env-vars-prefix CUSTOM_PREFIX_ 后,即可在路由响应中访问 CUSTOM_PREFIX_MY_VARIABLE。要禁用前缀,将其设为空字符串:--env-vars-prefix '' 或 --env-vars-prefix=。
该前缀同样作用于通过 Admin API 写入环境变量:键名不以该前缀开头时会被自动补上;当前缀为空时,Admin API 的写入会被拒绝,以防止任意修改环境变量(如 PATH、NODE_OPTIONS)。默认前缀常量 defaultEnvironmentVariablesPrefix = 'MOCKOON_' 定义在 packages/commons/src/constants/common.constants.ts。
禁用路由
可以在运行时按以下方式禁用路由:
- 提供路由的 UUID;
- 提供路由路径中包含的关键字(不带前导斜杠);
- 提供文件夹名中的关键字,可禁用该文件夹(含子文件夹)下的所有路由。
这对应桌面应用中的 "Toggle route" 功能(右键路由 → "Toggle route")。例如要禁用名为 folder1 的文件夹下所有路由,以及路径中包含 "users" 的所有路由:
$ mockoon-cli start --data ~/data.json --disable-routes folder1 users
要禁用全部路由,使用 --disable-routes=* 或 --disable-routes "*"。
从源码看,disabledRoutes 会传入 MockoonServer 的 ServerOptions,其类型定义于 packages/commons/src/models/server.model.ts:可接受 UUID 列表或包含路由部分路径的字符串(如 'users' 会禁用所有路径中包含 'users' 的路由)。
dockerize 命令
生成用于构建一个或多个 Mock API 自包含镜像的 Dockerfile。镜像构建完成后,运行容器时无需任何额外参数。该命令接受的标志与 start 命令类似,且生成的 Dockerfile 会默认启用 --disable-log-to-file。
请注意:该命令会把你用 --data 提供的 Mockoon 环境文件复制到生成的 Dockerfile 旁边。
用法:$ mockoon-cli dockerize
选项:
| Flag | 说明 |
|---|---|
| -d, --data | [必需] 指向你的 Mockoon 文件的路径或 URL |
| -p, --port | [必需] 在 Docker 容器中暴露的端口,数量需与 --data 提供的环境数据文件数量一致 |
| -o, --output | [必需] 生成的 Dockerfile 路径与名称(如 ./folder/Dockerfile) |
| -t, --log-transaction | 记录完整 HTTP 事务(请求和响应) |
| -h, --help | 显示 CLI 帮助 |
示例:
$ mockoon-cli dockerize --data ~/data.json --output ./Dockerfile
$ mockoon-cli dockerize --data ~/data1.json ~/data2.json --output ./Dockerfile
$ mockoon-cli dockerize --data https://file-server/data.json --output ./Dockerfile
从实现上看(packages/cli/src/commands/dockerize.ts):命令会校验 --data 与 --port 的数量是否一致;对于本地文件执行 fs.copyFile,对于 URL 执行 fetch 下载,统一复制到输出目录并规范为 .json 后缀;随后用 Mustache 模板渲染 Dockerfile(模板见 packages/cli/src/constants/docker.constants.ts),并生成包含数据文件名与端口的 ENTRYPOINT,最后打印构建命令提示。具体构建步骤见下文「使用 dockerize 命令」。
import 命令
导入 Swagger v2/OpenAPI v3 规范文件(YAML 或 JSON)。输出文件默认不美化,可用 --prettify 标志美化。
注意:该命令与桌面应用的导入功能类似,但不会直接导入到桌面应用。如需导入并在桌面应用中打开,请使用桌面应用的导入功能。
用法:$ mockoon-cli import
选项:
| Flag | 说明 |
|---|---|
| -i, --input [必需] | Swagger v2/OpenAPI v3 文件的路径或 URL |
| -o, --output [必需] | 生成的 Mockoon 文件路径与名称(如 ./environment.json) |
| -p, --prettify | 美化输出 |
| --disable-external-refs | 导入 OpenAPI 规范时禁用获取外部 HTTP/HTTPS $ref 引用(默认 false) |
| -h, --help | 显示 CLI 帮助 |
示例:
$ mockoon-cli import --input ~/input.json --output ./output.json
$ mockoon-cli import --input ~/input.yaml --output ./output.json
$ mockoon-cli import --input ~/input.json --output ./output.json --prettify
export 命令
将 Mock API 导出为 OpenAPI v3 规范文件(JSON 或 YAML)。JSON 输出默认不美化,可用 --prettify 美化。
用法:$ mockoon-cli export
选项:
| Flag | 说明 |
|---|---|
| -i, --input [必需] | Mockoon 数据文件的路径或 URL |
| -o, --output [必需] | 生成的 OpenApi v3 文件路径与名称(如 ./output.json) |
| -f, --format | 输出格式,"json" 或 "yaml"(默认 "json") |
| -p, --prettify | 美化输出(仅 JSON) |
| -h, --help | 显示 CLI 帮助 |
示例:
$ mockoon-cli export --input ~/input.json --output ./output.json
$ mockoon-cli export --input ~/input.json --output ./output.json --prettify
$ mockoon-cli export --input ~/input.json --output ./output.yaml --format yaml
从源码看(packages/cli/src/commands/export.ts),导出使用 commons 库中的 OpenApiConverter.convertToOpenAPIV3 完成转换;该转换器的单元测试可在 packages/commons/test/specs/openapi-converter.test.ts 中查看。
validate 命令
对照 schema 校验 Mockoon 环境 JSON 文件:
$ mockoon-cli validate --data ~/data1.json ~/data2.json
$ mockoon-cli validate --data https://file-server/data.json
💡
--data标志与start命令中的行为一致,可以传入多个路径或 URL 同时校验多个文件。
文件有效时输出:
✓ Valid environment: ~/data1.json
✓ Valid environment: ~/data2.json
✓ All environments are valid
有一个或多个文件无效时,会显示校验错误:
Invalid environment: ~/data1.json
- "name" is required
- "port" must be a number
Invalid environment: ~/data2.json
- "routes" must be an array
» Error: Environments validation failed
⚠️ 该命令不校验 OpenAPI 规范文件。OpenAPI 文件由
start命令在将其作为--data参数运行时校验。
从源码看(packages/cli/src/commands/validate.ts),校验使用 commons 中的 EnvironmentSchemaNoFix(不做自动修复的 schema)配合 abortEarly: false 收集全部错误,逐条打印;CLI 测试目录中的 packages/cli/test/data/envs/broken.json 等文件可用于体验校验失败场景。
mcp 命令
启动一个 Model Context Protocol (MCP) 服务器,把 Mockoon Mock 暴露给 AI 助手(Claude、GitHub Copilot、Cursor 等)。
用法:$ mockoon-cli mcp
在终端中运行该命令会打印出需要添加到 MCP 客户端中的配置片段(process.stdin.isTTY 判断逻辑见 packages/cli/src/commands/mcp.ts)。
可用 MCP 工具:
| 工具 | 说明 |
|---|---|
list_mocks |
列出所有本地 Mockoon Mock 文件 |
start_mock |
从本地 Mock 文件启动一个 Mockoon Mock 服务器 |
stop_mock |
按 UUID 停止运行中的 Mock 服务器 |
list_running_mocks |
列出 MCP 会话中当前运行的所有 Mock 服务器 |
额外 Mock 目录:
默认情况下,MCP 服务器在桌面应用的默认存储目录中查找 Mockoon Mock 文件(Windows 为 %APPDATA%\mockoon\storage,macOS 为 ~/Library/Application Support/mockoon/storage,Linux 为 ~/.config/mockoon/storage)。这些平台路径的具体实现在 packages/cli/src/commands/mcp.ts 的 getMockoonStorageDir() 中。
要包含其他目录中的 Mock 文件,在 MCP 客户端配置中把 MOCKOON_DATA_DIRS 环境变量设为分号分隔的路径列表:
{
"servers": {
"mockoon": {
"command": "mockoon-cli",
"args": ["mcp"],
"env": {
"MOCKOON_DATA_DIRS": "/path/to/dir1;/path/to/dir2"
}
}
}
}
出现在多个目录中且 UUID 相同的 Mock 只会被列出一次(首次出现的目录优先)。list_mocks 实现中还通过 scanDirForMocks 读取环境 JSON 的 uuid、name、port 字段来生成条目列表。
示例:
$ mockoon-cli mcp
help 命令
返回某个命令的信息。
用法:$ mockoon-cli help [COMMAND]
参数和选项:
| Flag | 说明 |
|---|---|
| COMMAND | 要显示帮助的命令 |
| --all | 查看 CLI 中的全部命令 |
在 GitHub Action 中使用
官方维护了一个 GitHub Action,让你可以在 CI/CD 流水线中运行 Mockoon CLI。下面是一个每次推送到 main 分支时运行 Mock API 的示例工作流:
name: Mockoon CLI demo
on:
push:
branches:
- main
jobs:
mockoon-cli-demo:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run Mockoon CLI
uses: mockoon/cli-action@v2
with:
# Mockoon CLI version, default to 'latest'
version: 'latest'
# Mockoon local data file or URL
data-file: './mockoon-data.json'
# port, default to 3000
port: 3000
- name: Make test call
run: curl -X GET http://localhost:3000/endpoint
💡 如果在自己构建的 Action 中使用 CLI,别忘了在命令末尾加
&以后台运行,避免阻塞工作流:mockoon-cli start -d ./data-file.json &。
Docker 镜像部署
使用通用 Docker 镜像
官方在 Docker Hub 发布通用镜像(mockoon/cli)。该镜像基于 node:26-alpine,安装最新版 Mockoon CLI。镜像定义见 packages/cli/docker/Dockerfile:包含 curl(用于 healthcheck)与 tzdata(时区支持),并以非 root 用户 mockoon 运行,ENTRYPOINT 为 mockoon-cli start --disable-log-to-file(文件日志在 Docker 镜像中默认禁用,日志输出到 stdout/stderr 控制台)。
运行容器时,所有 mockoon-cli start 标志(--port 等)都必须提供。
方式一:挂载本地数据文件,并在命令末尾追加 mockoon-cli start 标志:
docker run -d --mount type=bind,source=/home/your-data-file.json,target=/home/mockoon/data/your-data-file.json,readonly -p 3000:3000 mockoon/cli:latest --data /home/mockoon/data/your-data-file.json --port 3000
方式二:直接向 mockoon-cli start 传递 URL,无需挂载本地文件:
docker run -d -p 3000:3000 mockoon/cli:latest -d https://raw.githubusercontent.com/mockoon/mock-samples/main/samples/generate-mock-data.json --port 3000
Docker Compose
也可以用 docker-compose.yml:
mock-server:
image: mockoon/cli:latest
command: ["--data", "/home/mockoon/data/your-data-file.json", "--port", "3000"]
healthcheck:
test: ["CMD-SHELL", "curl -f http://localhost:3000/your-healthcheck-route || exit 1"]
interval: 30s
timeout: 5s
retries: 2
start_period: 10s
volumes:
- /home/your-data-file.json:/home/mockoon/data/your-data-file.json:readonly
请注意:官方 Docker 镜像已包含
ENTRYPOINT(即mockoon-cli start --disable-log-to-file)。如果不覆盖它,使用 Docker Compose 的command时不要再包含mockoon-cli start。该配置还提供了可选 healthcheck,因此可以用docker compose up --detach --wait阻塞直到服务器能正常响应。此示例需要配置一个返回 200 状态码且无延迟的your-healthcheck-route路由。
使用 dockerize 命令
用 dockerize 命令生成新的 Dockerfile,构建出的镜像自带数据文件与启动参数,运行容器时不再需要任何 Mockoon CLI 专属参数。
- 运行
dockerize命令:
mockoon-cli dockerize --data ./sample-data.json --port 3000 --output ./tmp/Dockerfile
- 进入
tmp目录(Dockerfile 与环境文件已生成/复制于此):
cd tmp
- 构建镜像:
docker build -t mockoon-image .
- 运行容器:
docker run -d -p <host_port>:3000 mockoon-image
日志
日志文件位于 ~/.mockoon-cli/logs/{mock-name}.log(路径定义见 packages/cli/src/config.ts 中的 Config.logsPath),包含运行中 Mock 服务器产生的全部日志条目(所有级别)。Mockoon CLI(或主应用)的大多数错误并不致命,会被视为正常输出——例如进入的请求 JSON 体格式错误时,Mockoon 会记录一条 JSON 解析错误,但不会阻塞应用的正常运行。
由于 CLI 在前台运行,日志同时也会输出到 stdout(控制台)。
事务日志
使用 --log-transaction 标志时,日志将包含完整事务(请求和响应),信息与桌面应用 "Logs" 标签页中看到的一致。已知敏感头(authorization、proxy-authorization、cookie、set-cookie、x-api-key、api-key、x-auth-token)的值在 CLI 事务日志和 Admin API 响应中都会被替换为 [REDACTED];authorization / proxy-authorization 保留认证方案(如 Bearer [REDACTED])。请求和响应体不做修改。
示例:
{
"app": "mockoon-server",
"level": "info",
"message": "Transaction recorded",
"timestamp": "YYYY-MM-DDTHH:mm:ss.sssZ",
"environmentName": "Demo API",
"environmentUUID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"requestMethod": "GET",
"requestPath": "/test",
"requestProxied": false,
"responseStatus": 200,
"transaction": {
"proxied": false,
"request": {
"body": "{}",
"headers": [{ "key": "accept", "value": "*/*" }],
"method": "GET",
"params": [],
"query": "",
"queryParams": {},
"route": "/test",
"urlPath": "/test"
},
"response": {
"body": "{}",
"headers": [
{ "key": "content-type", "value": "application/json; charset=utf-8" }
],
"statusCode": 200,
"statusMessage": "OK"
},
"routeResponseUUID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"routeUUID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
}
transaction 模型定义在 packages/commons/src/models/server.model.ts(包含请求方法、URL 路径、路由、查询参数、响应状态码、响应头等字段)。
禁用日志
通过重定向 stdout 和 stderr 可禁用控制台日志:
- Unix:
mockoon-cli start --data ./data.json > /dev/null 2>&1
或:
mockoon-cli start --data ./data.json &> /dev/null
- Windows(cmd):
mockoon-cli start --data ./data.json 2> NUL
或:
mockoon-cli start --data ./data.json > NUL 2>&1
- Windows(PowerShell):
mockoon-cli start --data ./data.json 2> $null
或:
mockoon-cli start --data ./data.json > $null 2>&1
- 跨平台:使用
dev-null-cli包
mockoon-cli start --data ./data.json | npx dev-null
也可以使用 --disable-log-to-file 标志禁用文件日志(Docker 镜像中默认启用)。
结合测试验证 CLI 行为
CLI 的集成测试位于 packages/cli/test/specs,覆盖数据加载、数据校验、文件服务、文件监听、导入导出、dockerize、MCP 等场景。例如 packages/cli/test/specs/data-loading.test.ts 验证了「文件不存在时报错」「URL 内容非合法 JSON 时报错」等边界行为;packages/cli/test/specs/env-vars-prefix.test.ts 验证了自定义前缀下环境变量的注入。测试数据文件(如 packages/cli/test/data/envs 目录下的 JSON)可用于快速体验 CLI 的各种行为。
结语
Mockoon CLI 把桌面应用的完整 Mock 能力(模板、代理、规则、Admin API、TLS 等)浓缩为一个可随处运行的前台进程。无论是本地开发、CI 流水线、Docker 容器,还是通过 MCP 协议接入 AI 助手,mockoon-cli 都提供了对应的官方方案。需要深入了解各功能的详细配置,可查阅官方文档,或直接阅读本仓库中 packages/cli 的源码与测试。