本地测试 Stripe Webhook 让你在上线生产前就能在自己的机器上验证支付事件处理逻辑。你在本地运行应用，通过公网 HTTPS URL 对外暴露，并在签名验证完全保留的情况下接收真实的 Stripe 测试模式事件。
为什么 Stripe Webhook 需要公网 URL
Stripe 通过公网把 Webhook 事件投递到配置好的端点 URL。像 127.0.0.1:3000 这样的地址 Stripe 服务器无法访问，因此本地开发需要一座桥梁。localhost 隧道 会把一个公网 HTTPS URL 映射到你的本地进程，无需修改路由器或防火墙。
测试前你需要准备什么
- 处于测试模式的 Stripe 账户。
- 带有 Webhook 路由的本地应用（例如
/api/webhooks/stripe）。 - 在环境变量中配置好的 Stripe Webhook 签名密钥。
- 能为签名校验保留请求头的隧道工具。
分步操作：用 PortPreview 在本地测试 Stripe Webhook
- 在目标端口上本地启动你的应用。
- 运行
npx portpreview 3000生成公网 HTTPS URL。 - 在 Stripe 控制台进入 开发者 → Webhooks，添加隧道 URL 加上你的 Webhook 路径。
- 选择你要测试的事件（例如
checkout.session.completed、invoice.paid）。 - 从 Stripe 控制台或 CLI 触发测试事件，并检查每一次投递。
- 确认你的处理器返回 2xx 响应且签名校验通过。
PortPreview 会捕获请求头、请求体和响应状态，让你无需仅凭服务器日志猜测，就能调试失败的投递。
在本地验证 Stripe Webhook 签名
开发期间切勿关闭签名校验。Stripe 用你的 Webhook 密钥对每个负载签名，你的处理器应当像在生产中一样精确校验 Stripe-Signature 头。保留原始请求头的隧道工具让你能够测试真实的代码路径。
本地测试中常见的签名失败：
- 使用了错误的 Webhook 密钥（控制台密钥与 CLI 密钥混用）。
- 在校验前读取已解析的 JSON 请求体，而非原始请求体。
- 时钟偏差超出 Stripe 的容差窗口。
值得在本地测试的事件
结账与订阅
测试 checkout.session.completed、customer.subscription.created 和 invoice.payment_failed，以确认开通、访问授权和催款逻辑。
Connect 与平台市场流程
如果你使用 Stripe Connect，请在上线前用测试关联账户验证账户更新事件和转账通知。
幂等性与重试
Stripe 会重试失败的投递。使用 Webhook 重放 确认你的处理器能安全处理重复事件。
Stripe CLI 与 localhost 隧道
Stripe CLI 可以用 stripe listen --forward-to 转发事件，适合快速检查。localhost 隧道给你一个稳定的公网 URL，可以粘贴进控制台、与队友共享，并用于多个服务商——不只是 Stripe。许多团队两者并用：CLI 用于快速迭代，隧道用于贴近生产配置的集成测试。
何时从本地转向预发布
本地测试涵盖处理器逻辑、负载解析和签名校验。对于受管密钥、数据库迁移和端到端发布流水线等环境相关的检查，请转向预发布环境。对于日常的支付功能开发，本地 Stripe Webhook 测试把迭代时间从几分钟缩短到几秒。
阅读我们关于 在本地调试 Webhook 的完整指南，或 加入 PortPreview 等候名单 体验以 Webhook 为先的隧道工作流。