確認部署環境與 Cloudflare 資源
確認帳戶、專案狀態與資源繫結，避免混淆首次初始化、遠端更新和本機開發。
Saavo 的正式應用程式在 Cloudflare Workers 上執行，業務資料、檔案、內容和背景工作分別使用不同資源。部署前先確認資源屬於哪個帳戶，以及目前專案是否已初始化，後續才能選擇正確指令。
Cloudflare 註冊和 R2 啟用步驟請見準備 Cloudflare，這裡主要檢查專案與帳戶之間的關係。
一、確認目前操作的專案
在應用程式根目錄檢查 package.json 和 wrangler.jsonc，確認這是準備上線的業務專案。目前範本提供下列部署入口：
npm run deploy:init
npm run deploy:update
npm run domain:set -- https://app.example.com這裡只列出入口供核對，實際執行順序請見首次部署與後續更新。不要將 Saavo 官網本身的建置指令碼當成新應用程式的部署指令，也不要因為舊教學提到 deploy:prod，就自行補上一個同名指令碼。
接著確認專案狀態：
- 尚未初始化：Worker 和資源名稱仍待確認，D1 的
database_id、KV 的id尚未透過部署寫入。 - 已初始化：
wrangler.jsonc已記錄帳戶和資源 ID，遠端存在對應的 Worker。 - 初始化中斷：部分資源已存在，但資料庫遷移、KV 同步或健康檢查尚未完成。
第三種狀態需要先排查，不能直接歸類為「還沒部署過」。
二、核對 Cloudflare 帳戶
在終端機執行：
npx wrangler whoami如果尚未登入，再執行：
npx wrangler login同一位 Cloudflare 使用者可能可以存取多個帳戶。請檢查 whoami 輸出的帳戶清單，確認準備部署的帳戶與 wrangler.jsonc 的 account_id 一致。
首次部署時，指令碼可以讓你選擇帳戶並寫入設定。後續更新會檢查目前身分是否能存取已記錄的帳戶，不會自動將專案遷移到另一個帳戶。
如果使用部署主機或 CI，部署驗證資訊應放在執行環境的驗證資訊設定中。這些資訊提供發布工具所需的權限，不屬於應用程式的執行階段變數，不要寫入 .env.production。
三、認識範本使用的資源
| 繫結或設定 | Cloudflare 資源 | 用途 |
|---|---|---|
Worker 的 name | Worker | 接收頁面、API、佇列和排程觸發的請求 |
DB | D1 | 使用者、訂單、權限、客服案件及業務資料 |
ANALYTICS_DB | D1 | 流量統計資料，與主要業務資料庫分開 |
MAIN_KV | KV Namespace | 文件、部落格內容，以及專案使用的 KV 資料 |
MAIN_R2 | R2 Bucket | 上傳檔案等物件資料 |
ASYNC_POLICY_TASK_QUEUE | Queue | Reaction 背景業務工作 |
ASYNC_LOGGER_QUEUE | Queue | 非同步記錄寫入 |
ANALYTICS_QUEUE | Queue | 流量統計事件 |
durable_objects.bindings | Durable Objects | 速率限制、計數、Nonce、Token Bucket 與 Timer |
triggers.crons | Cron Triggers | 依排程觸發權益檢查和資料維護 |
預設設定會保留這些資源。即使第一版暫時不使用某項介面功能，也不要只憑名稱刪除繫結，相關服務和背景入口可能仍依賴它。
DB 與 ANALYTICS_DB 必須指向不同的 D1。兩者的資料表結構、維護工作和資料用途不同，不能為了減少設定而填入相同 ID。
四、首次部署由指令碼建立資源
新專案使用 npm run deploy:init。指令碼會先檢查目標帳戶和資源名稱，確認後透過部署流程建立、繫結資源，並將產生的識別資訊記錄在專案設定中。
因此，通常不需要事先執行一組 wrangler d1 create、kv namespace create 和 queues create 指令。如果同名資源已存在，初始化檢查就會停止，不會預設接管這些資源。
範本初始的 D1、KV 設定不含可跨帳戶共用的正式環境 ID。資源名稱也會依 Worker 名稱調整，例如 Worker 名稱為 my-app 時，主資料庫會使用 my-app-db 作為名稱。
首次部署需要帳戶已能使用 R2。如果提示尚未啟用 R2，請先依事前準備啟用後再繼續。權限檢查失敗時，也要先核對帳戶和授權，不要修改資源 ID 來略過錯誤。
Durable Objects 的類別註冊會隨部署，透過 wrangler.jsonc 中的遷移設定處理，不需要手動建立物件實例。已發布的遷移標籤不要任意重新命名或回復舊版本。
五、既有專案只需檢查繫結
完成首次部署後，執行：
npm run doctor:remote它會檢查正式環境檔案、繫結設定、遷移檔案和目前的 Cloudflare 身分。ERROR 會使檢查失敗，WARNING 則需要依你啟用的功能判斷。例如第一版不收款時，尚未設定 Stripe 可以是預期狀態。
doctor:remote 不是完整的線上業務探測，也不會逐一驗證郵件、付款和所有資源內的資料。通過後，仍須在 Cloudflare 中核對 Worker 的繫結，並依後文驗證業務流程。
建議保留下列部署紀錄：
- 程式碼提交或發布版本。
- Cloudflare 帳戶和 Worker 名稱。
- 主資料庫、統計資料庫、KV、R2 與 Queue 的對應關係。
- 正式網域、最近部署時間和使用的指令。
資源 ID 記錄在專案設定中，方便後續更新，金鑰則分開管理。不要在部署紀錄中貼上完整的 Secret。
六、本機、正式環境與額外業務服務
本機 npm run dev 使用的資料庫狀態，與遠端 D1 並不是同一份資料。部署後看不到本機測試帳號是正常現象，不要因此將整個本機測試資料庫覆寫到正式環境。
.env.production 是目前專案部署時使用的正式環境設定檔，不代表範本已自動提供一個名為 production 的 Wrangler environment。目前預設流程使用專案的最上層資源設定，不需要額外加上 --env production。
如果需要獨立的預覽環境，應明確準備獨立的 Worker、資源繫結、網域和供應商測試設定。只複製環境檔案，不會自動隔離資料庫和佇列。
實作教學中的 PDF Worker 是業務功能新增的相依服務，通用部署指令碼不會自動發布它。上線前請先部署這類服務，再確認主網站的 Service Binding、驗證資訊和呼叫約定。實際產品需要哪些相依服務，以自己的業務實作為準。
下一步：準備正式環境設定與金鑰。