emulate CLI命令速查手册:start、init、list全部参数与实战用法

原创2026-10-10 12:56:291,830 阅读

emulate CLI命令速查手册:start、init、list全部参数与实战用法

emulate 是一个用于 CI 和无网络沙箱 的本地 API 模拟器(Local API emulation),一条命令即可在本地拉起 GitHub、Vercel、Stripe、Slack 等 14 个服务的"高保真替身"——不是 mock 假数据,而是完整有状态的生产级 API 仿真。本文带你 10 分钟吃透 start、init、list 三大核心命令的全部参数与实战用法,从此告别"测试要联网、要真实 Token"的烦恼。

核心关键词:emulate CLI、本地 API 模拟器、无网络沙箱;长尾词:emulate start 参数、emulate init 配置生成、无网络环境测试 API

1. 什么是 emulate?30 秒了解这个项目 🚀

emulate 的定位非常清晰:把生产环境依赖的第三方 API,原封不动搬到 localhost。

  • ✅ 完全有状态(stateful):创建、更新、删除操作都会真实持久化在内存里,请求之间相互影响,行为和线上 API 一致
  • ✅ 零配置启动:npx emulate 一行命令,14 个服务自动按 4000+ 端口依次就位
  • ✅ 支持自定义:可以用 YAML/JSON 种子文件预置数据,也可以编写自己的有状态 HTTP API
  • ✅ 面向 CI 设计:让流水线在无网络沙箱里照常运行测试

它内置支持的服务包括:Vercel、GitHub、Google、Slack、Apple、Microsoft、Okta、AWS、Resend、Stripe、MongoDB Atlas、Clerk、Linear、Twilio。

💡 项目主入口说明见 README.md,CLI 包源码位于 packages/emulate/,完整命令注册逻辑在 packages/emulate/src/index.ts。

2. 安装与快速上手:从 0 到第一个本地 GitHub

无需安装任何全局依赖,Node 环境直接用 npx 即可。

最快启动方法:零配置一键拉起

# 启动全部 14 个服务(默认基端口 4000)
npx emulate

# 等价写法(start 是默认子命令)
npx emulate start

启动后终端会打印每个服务的 URL 和 Inspector 检查器链接:

emulate

  vercel  http://localhost:4000
    Source: built-in
    Inspector: http://localhost:4000/_emulate

  github  http://localhost:4001
    Source: built-in
    ...

  Ready.

端口分配规则很简单:基端口 + 服务序号(代码见 project-runner.ts),例如默认 4000 下 Vercel 占 4000、GitHub 占 4001、Stripe 占 4009。打开 Inspector 链接就能在浏览器里查看每个服务的请求记录和实时状态,还能一键重置回种子数据。

emulate本地API模拟器配套的Stripe结算示例卫衣商品图

只启动需要的服务

测试脚本只依赖 GitHub 时,没必要拉起全部 14 个端口:

npx emulate --service github,vercel

--service 接收逗号分隔的服务名列表,只启动你点名的服务。

3. emulate start 命令:全部参数详解 🛠️

start 是默认子命令(不写命令名时等价于 emulate),它的完整参数表如下(注册源码见 index.ts):

参数 默认值 作用
-p, --port <port> 4000 基端口,各服务自动顺延分配;也支持环境变量 EMULATE_PORT 或 PORT
-s, --service <services> 全部 逗号分隔的服务白名单,如 vercel,github
--seed <file> 自动检测 指定种子配置文件(YAML 或 JSON)
--config <file> 自动检测 指定 TS / JS / YAML / JSON 配置(可包含自定义服务)
--watch 关 监听导入与 fixtures,修改后自动重载(重载会把状态重置回种子)
--base-url <url> 无 覆盖对外宣称的 Base URL,支持 {service} 模板变量
--portless 关 通过 portless 提供 HTTPS 域名(自动注册别名,见 portless.ts)
--generated-secrets-file <path> 无 将自动生成的服务密钥(如 GitHub App 私钥)写入一个新的仅属主可读的 JSON 文件

几个实用组合:

# 换个基端口,避开 3000/8080 等常用端口
npx emulate --port 3000

# 用指定种子文件启动(预置用户、仓库、商品等数据)
npx emulate --seed config.yaml

# 显式指定 TS 配置 + watch 热重载,边写自定义 API 边调试
npx emulate start --config emulate.config.ts --watch

⚠️ 注意:--config 和 --seed 不能同时使用;如果自动检测阶段发现了多个配置文件,emulate 会报错并要求你用 --config 明确指定(检测逻辑见 config-loader.ts)。

配置文件会自动找哪些文件名?

不传 --seed/--config 时,emulate 会在当前目录按固定顺序查找(完整列表同样在 config-loader.ts):

emulate.config.ts / .mts / .js / .mjs / .yaml / .yml / .json
service-emulator.config.yaml / .yml / .json

仓库里附带了一份覆盖全部服务的种子示例 emulate.config.example.yaml,包含 GitHub 用户/组织/仓库、Vercel 团队项目、Google 邮箱与日历、Stripe 客户与商品等,是理解种子结构最好的参考。

4. emulate init 命令:一键生成启动配置 ✨

init 帮你省去手搓 YAML 的麻烦,实现源码在 commands/init.ts:

# 生成覆盖全部服务的起步配置 emulate.config.yaml
npx emulate init

# 只生成某个服务的配置片段
npx emulate init --service vercel

执行后会在当前目录创建 emulate.config.yaml(已存在则报错退出),并提示你运行 npx emulate 启动。生成内容包含合理的默认数据:比如 GitHub 服务会预置 octocat 用户、my-org 组织、hello-world 仓库。

进阶用法:init --custom 脚手架式生成自定义 API 🏗️

这是 init 最强大的用法(脚手架实现见 commands/scaffold.ts):

npx emulate init --custom inventory

一条命令会同时生成三样东西:

  1. emulators/inventory.ts —— 一个类型完备的有状态 API 模块(库存查询、预订、取消、缺货 409 错误全都有)
  2. emulators/inventory.test.ts —— 可直接运行的 Node 测试(node --test 即可验证预订/取消/重置行为)
  3. 配置文件更新 —— 自动把 inventory 服务注册进现有的 YAML/JSON/TS/JS 配置;遇到无法自动改写的配置时,会打印需要你手动添加的 import 语句和服务条目

生成后按提示启动即可:

npx emulate start --watch   # watch 模式缺失的本地导入会自动重试

仓库里有一个完整的成品示例 examples/custom-api/,包含 emulators/inventory.ts 实现与 emulators/inventory.test.ts 测试,以及 emulate.config.ts 注册方式,照着抄就能跑。

5. emulate list 命令:服务清单与能力速查 📋

npx emulate list
# 等价别名
npx emulate list-services

输出分两部分(实现见 commands/list.ts):

  • Available services:内置 14 个服务的名称 + 各自覆盖的端点摘要(如 GitHub 一行就列出了 users、repos、issues、PRs、checks 等全部能力域)
  • Configured instances:如果你的配置里注册了自定义服务,会在这里显示名称和来源路径

不知道某个端点归哪个服务管?先跑一遍 list,相当于内置的"能力目录"。

6. 实战场景:从 CI 到支付闭环 🔥

场景一:CI 无网络沙箱里跑集成测试

核心思路:测试进程和模拟器用同一份种子,端口固定。

# 流水线里:先起模拟器(或全局安装 emulate 后直接 emulate start)
npx emulate start --service github,stripe --seed ci-seed.yaml &

# 应用测试指向本地端口
GITHUB_API_URL=http://localhost:4001 \
STRIPE_API_URL=http://localhost:4009 \
npm test

由于模拟器完全有状态,你的测试可以真实走通"建仓 → 发 issue → 合并 PR"这类多步链路,而不需要 mock 每个请求。

场景二:本地 Stripe 结算全流程(含商品图)🛒

emulate 的 Stripe 服务模拟了完整的 Checkout 流程,并且仓库内置了一个可运行的商店示例 examples/stripe-checkout/——商品种子直接来自配置文件,Webhook 带 Stripe-Signature 签名校验。

示例中的商品列表:

emulate Stripe本地模拟器示例商店的马克杯商品图

emulate Stripe本地模拟器示例商店的黑色T恤商品图

种子配置只需几行(参考 emulate.config.example.yaml 中的 stripe 段):

stripe:
  customers:
    - email: test@example.com
      name: Test Customer
  products:
    - name: Pro Plan
      description: Monthly pro subscription
  prices:
    - product_name: Pro Plan
      currency: usd
      unit_amount: 2000

启动后本地 http://localhost:4009 就是完整的 Stripe API,配合上面的 Next.js 商店示例,支付下单、Webhook 回调、订单落库全链路本地闭环,一分钱不花、一个真实 Token 不用申请。

场景三:给框架嵌入 HTTPS 本地域名(portless)

有些 SDK 或 OAuth 回调强制要求 HTTPS。emulate 集成 portless 后,每个服务自动获得形如 https://github.emulate.localhost 的可信域名(实现见 portless.ts 与启动流程 project-start.ts):

portless proxy start        # 首次需启动 portless 代理
npx emulate start --portless

不想装 portless 也可以直接 --base-url "https://{service}.myproxy.test" 套任意反代,{service} 会被替换成服务名(解析优先级见 base-url.ts:种子内 per-service baseUrl > CLI --base-url > 环境变量 EMULATE_BASE_URL > 默认 localhost)。

场景四:watch 模式开发自己的有状态 API

写自定义模拟器时,--watch 是最好的搭档:修改 emulators/xxx.ts 保存后自动重载,重载成功即重置状态回种子,缺失的本地导入会在文件创建后自动重试。开发体验相当于"模拟器的热重载开发服务器"。

7. 常见坑与 FAQ ❓

Q1:端口被占了怎么办? 改基端口即可:npx emulate -p 5000,或设环境变量 EMULATE_PORT=5000。单个服务也可以在种子配置里单独指定 port,冲突时 emulate 会明确报 Duplicate port 错误而不是静默错乱。

Q2:init 提示"Config file already exists"? 说明当前目录已有 emulate.config.yaml,init 不会覆盖现有配置。直接编辑现有文件,或用 init --service xxx 参考生成的片段手动合并。

Q3:启动后数据如何重置? 两种方式:--watch 下修改文件触发重载即自动重置到种子;或直接打开对应服务的 Inspector 页面(<服务URL>/_emulate)点击重置。

Q4:密钥/Token 从哪来? 内置服务都有默认 token(见 registry.ts 的 DEFAULT_TOKENS);GitHub App 的 private_key 可以省略,配合 --generated-secrets-file .emulate-secrets.json 让 emulate 自动生成 RSA-2048 密钥并写入仅属主可读的文件(Linux 需要 setfacl/getfacl,Windows 不支持该参数)。

Q5:怎么确认某个端点支持不支持? 跑 npx emulate list 看端点摘要,或查阅仓库 README 中按服务分章的端点清单(README.md 从 Vercel API 到 Twilio 全部列出),也可以直接浏览各模拟器包的实现,如 packages/@emulators/。

8. 命令速查表:一张表带走全部要点 ⚡

你想做的事 命令
零配置拉起全部 14 个服务 npx emulate
只启动指定服务 npx emulate --service github,vercel
更换基端口 npx emulate --port 3000
用种子数据启动 npx emulate --seed config.yaml
生成起步配置 npx emulate init
为单个服务生成配置 npx emulate init --service vercel
脚手架生成自定义 API + 测试 npx emulate init --custom inventory
查看服务清单与端点能力 npx emulate list
自定义 API 热重载开发 npx emulate start --watch
本地 HTTPS 域名(portless) npx emulate start --portless
覆盖对外 Base URL(反代场景) npx emulate start --base-url "https://{service}.myproxy.test"
自动生成并导出服务密钥 npx emulate start --generated-secrets-file .emulate-secrets.json
查看版本号/帮助 npx emulate --version / npx emulate --help

写在最后

emulate 把"测试依赖第三方 API"从一件需要申请 Token、担心限流、依赖网络的事,变成了一条 npx emulate 就能完成的本地操作。掌握 start 的参数组合、init 的配置生成和 list 的能力速查,你就拥有了在无网络沙箱里复刻整套生产依赖的能力。现在就去试试,在你的 CI 或本地测试里跑通第一个本地 GitHub 吧 🚀

登录后查看全文
emulate