Saavo

首次部署

透過 deploy:init 建立 Cloudflare 資源、寫入正式環境設定，並部署到 workers.dev。

首次部署不需要手動建立 D1、KV、R2 Bucket 和 Queue，也不要自行將資源 ID 填入 wrangler.jsonc。專案提供的 deploy:init 會檢查目標帳戶和資源名稱，在你確認後完成整個初始化流程。

部署前準備

開始前，請確認以下項目已就緒：

  • Cloudflare 帳號已驗證，且準備部署的帳戶已啟用 R2。
  • 已決定 Turnstile 要暫用官方測試金鑰，或使用正式 Widget 的 Site Key 和 Secret Key。
  • 如果仍使用預設郵件服務 Resend，已準備好 Resend API Key。
  • 已決定寄件者地址和支援信箱。
  • 如果準備同時啟用 Stripe，已準備好連線識別碼、Secret Key 和 Webhook Secret。

如果目前只有 Cloudflare 指派的 workers.dev 網址，可以先使用範本內附的 Turnstile 測試金鑰。確定正式網域後，再建立 Widget、替換 .env.production 中的金鑰並重新部署。完整流程請參閱設定 Turnstile。未啟用 Stripe、OAuth 或通知服務時，不需要為了部署而臨時註冊。

遠端設定寫入 .env.production

.env 繼續用於本機開發。Turnstile、Resend 和 Stripe 的遠端環境設定，會在 deploy:init 互動流程中輸入，並存入 .env.production。Turnstile 測試金鑰也應填在這裡，不能因為使用測試值，就讓遠端部署讀取本機 .env。這兩個檔案都不會提交到 Git。

登入 Cloudflare

在專案根目錄執行：

npx wrangler login

瀏覽器會開啟 Cloudflare 授權頁面。

Cloudflare 授權

確認登入的使用者能存取準備部署的帳戶，再允許 Wrangler 存取。完成授權後，可以執行以下指令核對：

npx wrangler whoami

終端機會輸出目前授權的帳號資訊和權限清單：

wrangler whoami

如果看到多個帳戶，請記住這個專案應使用哪一個。deploy:init 會在終端機讓你選擇。

執行首次部署

執行：

npm run deploy:init

依終端機提示，按順序完成：

  1. 選擇 Cloudflare 帳戶。
  2. 確認 Worker 名稱，以及由它衍生的資源名稱。
  3. 輸入成對的 Turnstile Site Key 和 Secret Key。首次驗證部署時，可使用官方測試組合。
  4. 確認寄件者地址和支援信箱。
  5. 使用預設的 Resend 時，輸入 RESEND_API_KEY。
  6. 選擇是否現在設定 Stripe。
  7. 確認寫入 .env.production。
  8. 查看準備建立的 Worker、D1、KV、R2 和 Queue，確認後開始部署。

首次部署

指令碼不會沿用或覆寫同名的既有資源。如果偵測到名稱衝突，會停止並說明衝突位置。確認資源歸屬前，不要為了繼續執行，就任意刪除 Cloudflare 帳戶中的內容。

確認後，指令碼會自動完成型別檢查和正式環境建置、建立並繫結 Cloudflare 資源、部署 Worker、遷移遠端資料庫、同步 KV，最後檢查首頁和已啟用的內容頁面。

部署成功後，終端機會顯示類似以下的網址：

https://my-project.<你的-workers.dev-子網域>.workers.dev

首次部署成功

開啟這個網址，確認首頁和 /docs 可以存取。

首次開啟 docs 頁面

使用官方測試組合時，可以繼續驗證註冊等表單是否正常串接，但它不會辨識真正的機器人。如果使用正式 Widget，還需確認 Hostname 清單包含瀏覽器網址列中的實際主機名稱。

中途結束後如何繼續

如果在設定檢查階段結束，且尚未建立遠端資源，修正終端機指出的問題後，可以重新執行：

npm run deploy:init

如果 Worker 或部分資源已建立，請先檢查遠端狀態和本機繫結，不要直接重複初始化。若在資料庫遷移、KV 同步或健康檢查階段失敗，請依部署中斷處理繼續操作。

成功完成首次部署後，專案已記錄 Cloudflare 帳戶、資源 ID 和正式環境。後續修改程式碼或 .env.production 時，改用：

npm run deploy:update

不要在已初始化的專案反覆執行 deploy:init，也不要繞過專案指令碼，另外維護一組 Wrangler Secrets。

使用自訂網域

首次部署必須先在 workers.dev 完成。準備切換到已由 Cloudflare 管理的正式網域時，執行：

npm run domain:set -- https://app.example.com

指令會更新網站網址和 Worker Custom Domain，重新驗證並部署專案。切換網域前，建議先在 Turnstile 建立正式 Widget，並將實際金鑰寫入 .env.production，讓 domain:set 一併套用新金鑰部署。如果先綁定網域、之後才替換金鑰，則修改 .env.production 後，再執行 npm run deploy:update。

切換網域後，還需分別處理 Resend 的寄件網域、OAuth 回呼網址和 Stripe Webhook。終端機會顯示目前專案對應的回呼網址，逐項複製到各服務後台即可。

到這裡，專案已完成從 Saavo 範本到 Cloudflare 的第一次完整部署。接著進入實作，開始修改產品內容。準備開放實際使用者使用時，再依部署上線完成正式檢查。