emulate CLI命令速查手册:start、init、list全部参数与实战用法
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 链接就能在浏览器里查看每个服务的请求记录和实时状态,还能一键重置回种子数据。
只启动需要的服务
测试脚本只依赖 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
一条命令会同时生成三样东西:
emulators/inventory.ts—— 一个类型完备的有状态 API 模块(库存查询、预订、取消、缺货 409 错误全都有)emulators/inventory.test.ts—— 可直接运行的 Node 测试(node --test即可验证预订/取消/重置行为)- 配置文件更新 —— 自动把
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.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 吧 🚀


