疑難排解

遇到問題時，先確認「哪一步尚未完成」，再決定要修改什麼。本章依目前預設範本的實際流程分為六篇，將同一業務流程中的問題放在一起，避免在驗證、電子郵件、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。變更設定或服務供應商設定後，還要實際驗證對應業務，編譯通過不能證明外部服務可用。

常見錯誤速查

需要查詢精確欄位時，請使用參考手冊。需要從頭完成一次發布時，請使用部署上線。