企业官网建设流程全解析

emulate是一个本地 API 仿真（emulation）工具，把 Twilio、Resend、Stripe 等 14 个云服务变成带状态、可落地的本地服务——不是 mock，而是“生产保真”的替代品。本文面向新手，带你跑通仓库里 3 个官方示例项目：用 emulate 本地验证短信验证码（SMS OTP）、邮件 Magic Link 登录与Stripe 结账支付，全程不消耗一条真实短信、一封真实邮件、一分真实款项。

为什么这3个场景最需要“本地验证”

这 3 个示例都基于同一个思路：把官方 SDK 指到本地模拟器，你的业务代码一行不改，却能在没有网络的环境（CI、离线沙箱）里完成端到端验证。

30秒一键启动：3个示例项目怎么跑

所有示例位于仓库的 examples/ 目录，是 pnpm monorepo 的子包，统一从仓库根目录启动：

pnpm install pnpm --filter twilio-sms-verification dev # 或 resend-magic-link / stripe-checkout

然后打开http://localhost:3000即可。三个项目的模拟器都通过一个内置路由挂载到应用自身（如/emulate/twilio/*），因此不需要单独再启动一个npx emulate服务进程。

示例一：Twilio 短信验证码本地验证

📱 项目位置：examples/twilio-sms-verification/

这个 Next.js 应用演示了完整的手机号 + 短信 OTP 验证流程：输入手机号 → 服务端用官方 Twilio SDK发起验证 → 跳转验证页 → 输入验证码 → 建立会话进入仪表盘。

新手友好的两个关键点：

1. 固定验证码：种子数据里预置了 Verify 服务，任何手机号都接受验证码123456，你完全不需要“收到”任何短信；
2. 可视化工具：访问/emulate/twilio/?tab=verify可以在浏览器里直接查看每次验证请求和已下发的验证码，测试时想取码就用 curl 调模拟接口，自动化脚本和人工验证都能覆盖。

SDK 如何指向本地？核心只有一步——在 src/lib/twilio.ts 中安装自定义请求客户端，把api.twilio.com、verify.twilio.com等官方域名改写到本地/emulate/twilio/...路径前缀下。业务逻辑代码保持与生产环境完全一致。

示例二：Resend 邮件 Magic Link 本地登录

📧 项目位置：examples/resend-magic-link/

Magic Link 登录是“输入邮箱 → 收到带 6 位验证码的邮件 → 登录”的免密方案，用 Resend 这类邮件 API 实现。痛点在于：本地开发时邮件真的发出去了，你却没法可靠地看到它。

这个示例的解法是：Resend SDK 通过RESEND_BASE_URL指向http://localhost:3000/emulate/resend，每一封“发出的邮件”都被模拟器完整保存在内存中，提供两条查看路径：

• 收件箱 UI：访问/emulate/resend/inbox，像逛邮件客户端一样浏览每封邮件的 HTML 内容；
• REST API：GET /emulate/resend/emails列出全部邮件，按 ID 还能取单封——测试脚本可以直接从邮件 HTML 里正则提取 6 位验证码，实现无人值守的完整登录流验证。

SDK 客户端定义在 src/lib/resend.ts，会话与验证动作在 src/app/actions.ts。整个登录闭环——发送、取码、校验、建会话——全部发生在 localhost。

示例三：Stripe 结账全流程本地支付

💳 项目位置：examples/stripe-checkout/

这是三者中最“重”的一个：一个完整的 Next.js 电商前台，演示从商品目录到支付成功的 Stripe Checkout 全流程。

预置了4个商品（卫衣、马克杯、T恤、贴纸包），自动播种进本地 Stripe 服务：

完整流程只有 6 步，全部零真实扣款：

1. 首页通过官方stripeSDK 从本地模拟器拉取商品与价格；
2. 用户把商品加入购物车（localStorage 持久化）；
3. 点击结账，服务端 action 创建一个 Checkout Session；
4. 浏览器跳转到本地托管的结账页，点“Pay and Complete”；
5. 模拟器把会话标记为已支付，并向你的/api/webhooks/stripe发出真实的checkout.session.completedwebhook（带合法的Stripe-Signature签名头）；
6. webhook 处理器落库订单，用户被重定向到成功页看到订单确认。

对新手来说最值得学的是细节处理：SDK 配置为host: localhost，再配一层 src/app/v1/[...path]/route.ts 薄代理转发请求；webhook 处理在 src/app/api/webhooks/stripe/route.ts。你在这里学到的 webhook 验签、订单落库模式，拿到生产 Stripe 上照样能用。

3个项目共用的核心机制：内嵌式模拟器

你会发现三个项目都有一个共同文件：src/app/emulate/[...path]/route.ts。它由@emulators/adapter-next的createEmulateHandler生成（见 packages/@emulators/adapter-next/src/index.ts），作用是把 Twilio / Resend / Stripe 模拟器内嵌进你的 Next.js 应用，挂载在/emulate/前缀下：

• 同源于同进程：不需要额外端口，localhost:3000一个入口搞定应用 + 模拟器；
• 官方 SDK 直连：只需改写 baseURL（或加一层转发），SDK 的域名、路径、认证逻辑全部保留；
• 状态可观测：每个服务自带 Inspector 页面（如/emulate/twilio/?tab=verify、/emulate/resend/inbox），验证过的短信、邮件、订单都能点开细看。

Nuxt 用户也有对应适配器 packages/@emulators/adapter-nuxt/，参考 examples/nuxt-embedded/。

快速对照表：3个示例怎么选型

三个项目都遵循同样的最小改造原则：业务代码零改动，只改 SDK 的 baseURL。这正是 emulate 的价值——把“生产保真的 API”搬到 localhost，让你在 CI 和无网络的沙箱里也能自信地验证短信、邮件与支付这类最依赖外部服务的流程。