故障排查

遇到问题时，先确认“哪一步没有完成”，再决定修改什么。本章按照当前默认模板的实际流程分为六篇，同一条业务链上的问题放在一起，避免在认证、邮件、OAuth 或支付、Webhook 之间反复跳转。

从现象找到文章

一、先固定复现条件

记录运行环境、代码版本、访问地址、操作时间和最短复现步骤。比如“生产环境，使用普通账号购买 yearly 套餐，Stripe 已付款，刷新产品页后仍不可用”，比“支付坏了”更容易定位。

本地和生产应分别观察，不要用本地 D1 中没有记录来推断生产支付未入库，也不要在本地修改 .env 后直接验证线上行为。

API 的 code 有时是数值结果码，有时属于第三方协议，也可能不存在。数值码可以在 src/errors.ts 中查询，不能把所有响应都当作完整的 APIResponse<T>。

分享排错信息时，隐藏 Cookie、Token、密钥、验证码和收件人信息。本地邮件预览会包含邮件正文，复制终端输出前也要检查。

二、先看诊断结果，再看业务结果

在初始化后的项目根目录，根据环境选择一个检查命令：

# 本地配置
npm run doctor

# 生产配置与 Cloudflare 账号可用性
npm run doctor:remote

doctor 会检查配置、变量、Binding 名称和数据库目录等。doctor:remote 读取 .env.production，还会检查远程资源 ID 是否填写，以及当前身份是否能访问配置中的账户。

它们不是完整的线上探测工具。检查通过不意味着每个资源真实存在，也不意味着 Resend 已投递邮件、Stripe 已完成回调或 Queue 已执行任务。未启用的可选服务可能显示提示或警告，应结合当前要验证的功能判断。

三、按最后一个成功步骤继续查

典型支付流程是：

创建 Checkout → 用户付款 → Webhook 验签
→ 支付记录更新 → 创建业务 Event → 执行 Command → 用户获得访问能力

如果已经收到正确的付款事件，就继续查看支付记录和权限处理，不必反复修改 Checkout 页面。如果还没有收到回调，就先解决回调地址、Secret 和投递问题。

后台任务同样如此。queue.send() 完成、消息被确认、Command 成功和外部服务最终完成是不同阶段，应分别验证。

四、修复后怎样确认

用同一个复现案例重新验证，并检查相关的失败场景。例如修正套餐映射后，既检查新付款能否开通，也检查重复回调是否没有重复发放。

代码修改后运行项目的 npm run verify。配置或服务商设置变更则还要实际验证对应业务，编译通过不能证明外部服务可用。

常见错误速查

需要查准确字段时，使用参考手册。需要从头完成一次发布时，使用部署上线。