部署、資源與網域
依發布失敗階段恢復部署，核對 Cloudflare 資源、環境變數、網域和線上內容。
部署並不是一筆不可分割的交易。指令碼最後失敗，不代表前面的遠端操作都未發生。排查前，請保留第一個錯誤、失敗階段、程式碼版本和時間，再確認線上目前的狀態。
一、選對專案與指令
| 情境 | 指令 |
|---|---|
| 全新專案首次建立遠端 Worker 和資源 | npm run deploy:init |
| 已有 Worker 和完整遠端繫結，發布後續變更 | npm run deploy:update |
| 綁定或更換正式網域 | npm run domain:set -- https://app.example.com |
這些指令屬於初始化後的應用程式專案。預設範本沒有 deploy:prod，也沒有要求使用 wrangler --env production 的正式環境分支。.env.production 是部署指令碼讀取的變數檔案，不等於 Wrangler 的具名環境。
不能只看到 account_id，就判定首次部署已完成。這個欄位可能在建立資源前就寫入，仍須繼續核對 Worker 和資源。
二、先確認帳戶與資源歸屬
npx wrangler whoami
npm run doctor:remote請核對目前身分能否存取 wrangler.jsonc.account_id，以及設定中的 Worker、D1 ID、KV ID、R2 和 Queue 名稱是否屬於目標專案。
doctor:remote 主要驗證本機的正式環境設定、資源識別碼是否已填入、命名關係，以及帳戶可用性。它不會逐一確認遠端 D1、KV、R2、Queue 都存在，也不會執行完整業務驗證。資源不存在時，還應在對應帳戶的主控台核對實際資源。
CLI 建立的名稱通常以專案名稱為前綴，例如 my-app-db。不要將範本預設名稱當成必須存在的遠端資源，更不要複製其他應用程式的資料庫 ID，只為了讓檢查通過。
三、首次部署中途失敗
先判斷停在哪一步，再選擇恢復方式：
| 失敗位置 | 可能已完成的內容 | 下一步 |
|---|---|---|
| 互動式設定或資源預先檢查 | 本機設定和 .env.production 可能已更新 | 修正設定，確認尚未建立遠端資源後，再執行首次部署 |
| 型別檢查或建置 | 部分本機檔案已修改，Worker 可能尚未發布 | 修正第一個程式碼或內容錯誤 |
| 建立資源或上傳 Worker | 部分遠端資源可能已存在 | 逐項核對資源與設定，不要盲目再次建立 |
| 遠端資料庫初始化 | Worker 可能已上線，其中一個資料庫可能已初始化 | 依資料庫章節確認兩個資料庫的狀態 |
| KV 同步 | Worker 和資料庫可能已準備就緒 | 使用同一版本的內容恢復同步 |
| 頁面健康狀態檢查 | 前面的部署可能已完成 | 直接檢查線上回應和 Worker 記錄 |
首次部署會先發布 Worker，再完成資料庫與內容準備。等到這些步驟全部成功後，才適合開放業務流量。
如果 Worker、D1 和 KV 等繫結已完整，修正故障後，可使用更新流程完成發布。如果只建立了部分資源，應先確認歸屬，以及是否已有資料，再修正缺少的設定，不要刪除同名資源或清空 ID，強制從頭開始。
詳細流程請見首次部署與後續更新。
四、更新部署在哪一步停止
目前 deploy:update 的主要順序如下：
核對帳戶、Worker、正式環境檔案、主金鑰和網站網址
→ doctor:remote → cf-typegen → verify
→ db:migrate:remote → 發布 Worker
→ kv:sync:remote → 頁面健康狀態檢查如果 verify 失敗，目前的更新流程就尚未執行後面的遠端遷移和發布。請先修正程式碼、型別、測試或建置，不應略過驗證直接發布。
如果遠端遷移失敗，前面的部分遷移可能已完成。如果 Worker 上傳失敗，資料庫可能已更新。此時必須確保舊 Worker 仍能使用現有結構，不能只回復舊版程式碼，就認為資料庫也已還原。
如果 KV 同步或健康狀態檢查失敗，新 Worker 可能已在線上執行。先查看部署版本和實際回應，再決定要重新執行更新，還是修正個別階段。
五、環境檔案正確，線上卻仍提示缺少設定
確認檢查的是哪份檔案、哪個 Worker，以及修改後是否已部署：
| 修改內容 | 必要後續操作 |
|---|---|
.env | 重新啟動本機開發並驗證，不會自動變更線上環境 |
.env.production | 執行更新部署，讓變數進入 Worker |
config/ 或介面語言資源 | 重新建置並部署 |
| OAuth 或 Turnstile 平台設定 | 在平台儲存並重新驗證，若應用程式驗證資訊變更，也需要部署 |
部署指令碼會區分一般變數與 Secret。以 VITE_ 開頭的變數可能進入瀏覽器端建置檔案，不能用來儲存金鑰。
空字串不會作為新值寫入遠端 Worker，檔案中缺少的遠端 Secret 也不會因此自動刪除。如果目的是停用舊整合，應依服務使用情況明確處理設定與遠端 Secret，不能只將檔案內容刪空。
如果出現 SAAS_SECRET must exist and match，請檢查 .env 與 .env.production 是否仍使用專案原始主金鑰。不要為了讓比較結果相等，就同時產生新值，這可能使既有資料無法解密。
Cloudflare 部署身分的 Token 屬於工具驗證資訊，不應放入應用程式的 .env.production，目前指令碼會拒絕這類欄位。
六、Binding 或 Durable Object 發生錯誤
先判斷錯誤發生在型別檢查，還是執行期間：
- 缺少型別時，核對
wrangler.jsonc後執行npm run cf-typegen。 - 執行時找不到 Binding，請檢查已部署版本和實際繫結，產生型別不會建立遠端資源。
- Queue 有訊息卻未處理時，請至背景工作與統計檢查三處名稱和取用者。
- Durable Object 發生錯誤時，比較
class_name與src/index.tsx實際匯出的類別名稱，並檢查遷移宣告。
目前範本匯出 RateLimiterDO、CounterDO、NonceDO、TokenBucketDO 和 TimerDO。新增或調整類別時，應依 Durable Object 遷移規則處理，不能任意修改已部署過的遷移標籤。詳細說明請見 Wrangler Durable Object 設定。
七、網域無法連線或反覆重新導向
先在瀏覽器 Network 中查看重新導向流程，判斷問題發生在 DNS、TLS、網站入口，還是登入流程。
| 現象 | 檢查方向 |
|---|---|
| 無法解析網域或連線失敗 | DNS、目標帳戶、網域設定和憑證狀態 |
| 不同網域之間循環重新導向 | VITE_SITE_URL、實際 Host、deploy.hosts 和 Proxy 重新導向規則 |
| 首頁正常，登入後失效 | Cookie 主機、通訊協定和 OAuth 回呼 |
| 僅在某個舊入口出錯 | 是否仍存取舊 Worker 或舊自訂網域 |
範本的正式環境網址要求完整 HTTPS Origin，不包含額外路徑、查詢參數或連接埠。設定正式網域請使用 domain:set，它會修改設定並重新部署，但不包含日常更新流程中的完整資料庫遷移和 KV 同步。
切換後，請分別核對 GitHub、Google、Stripe 和 Turnstile 設定。修改網站網址，不會自動更新第三方平台後台中的回呼或允許主機清單。
八、部署完成，卻仍是舊內容
先核對正在存取的網址和 Worker 版本，再處理快取。對於文件與部落格，也要分別檢查頁面導覽、內文和搜尋索引。
如果建置時產生的導覽或搜尋已更新，但遠端 KV 同步失敗，可能出現頁面結構是新的、內文卻是舊的情況。確認本機程式碼與目前發布版本一致後，可以單獨恢復內容同步：
npm run kv:sync:remote這是遠端寫入操作，應使用準備發布的正確內容版本。一般發布通常使用 deploy:update 一併更新建置檔案和 KV，不需要每次都重複手動同步。
/docs 或 /blog 傳回 404 時，也要檢查 deploy.content 對應開關、baseUrl、啟用語言和內容目錄。不要將所有 404 都視為 CDN 快取問題。
九、查看記錄與驗證恢復結果
在目標專案目錄啟動即時記錄，再重現一次失敗的請求：
npx wrangler tail也可以在 Cloudflare 主控台查看目標 Worker 的執行記錄。請記錄失敗路徑、時間、錯誤名稱和關聯 ID，分享前隱藏驗證資訊與個人資訊。指令說明請見 Wrangler Worker 指令。
健康狀態檢查僅檢查首頁和已啟用內容入口等頁面回應，不能證明註冊、付款、電子郵件或背景工作正常。修正後，請完成原本故障的操作，再依上線驗收驗證受影響的業務。