Mockoon CLI 完全指南:用 @mockoon/cli 在任意环境部署 Mock API

原创2026-10-13 19:43:121,705 阅读
文章标签:开发工具测试后端

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 专属参数。

  1. 运行 dockerize 命令:
mockoon-cli dockerize --data ./sample-data.json --port 3000 --output ./tmp/Dockerfile
  1. 进入 tmp 目录(Dockerfile 与环境文件已生成/复制于此):
cd tmp
  1. 构建镜像:
docker build -t mockoon-image .
  1. 运行容器:
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 的源码与测试。

登录后查看全文
mockoon