正式網域與第三方回呼
切換網站入口，核對 OAuth、Stripe、Turnstile 和郵件設定，完成正式網域驗收。
完成 workers.dev 的首次部署後，就可以將網站切換到正式網域。本篇使用 https://app.example.com 作為範例，實際操作時，請將所有網址替換成自己的網址。
購買網域、加入 Cloudflare、接收郵件和設定檔案網域的步驟，已有網域設定教學。這裡著重於網站切換，以及依賴該網址的服務。
一、切換前確認準備完成
- 目標網域已加入部署 Worker 所屬的 Cloudflare 帳戶，Zone 處於可用狀態。
- 專案已完成首次部署，Worker 與資源繫結都存在。
.env.production已存在，SAAS_SECRET與本機專案一致。- 已決定唯一的正式入口，例如使用
app.example.com，或直接使用根網域。 - Turnstile 已準備好正式網站設定，OAuth 與付款回呼也已整理完成。
Cloudflare Custom Domain 要求網域屬於可用的 Zone，同名主機若已有 CNAME，也會影響建立。發現衝突時，請先確認舊記錄的用途，不要直接刪除仍在服務其他應用程式的 DNS 記錄。平台要求請見 Custom Domains 官方說明。
二、執行網域指令
在應用程式根目錄執行：
npm run domain:set -- https://app.example.com目前指令碼會：
- 檢查帳戶、Worker、正式環境和金鑰一致性。
- 執行
doctor:remote。 - 在
wrangler.jsonc中寫入目標 Custom Domain。 - 更新
.env.production的VITE_SITE_URL。 - 重新建置、部署，並同步該檔案中的非空白變數與 Secret。
- 檢查新網域的首頁，印出 OAuth 與 Stripe 回呼網址。
需要注意的是，指令碼會保留非 Custom Domain 的路由，但會用本次目標替換設定中的 Custom Domain 項目。它適合用來設定目前的正式入口，不是反覆執行就能持續新增多個網域的指令。
指令碼也不會自動修改第三方平台、R2 檔案網域、郵件服務設定或業務程式碼中寫死的 URL。自訂 hosts、統計允許的網域和業務回呼，仍須依自己的設定核對。
三、網域切換失敗時先看哪一步
如果設定寫入或建置階段失敗，指令碼會將本機的 wrangler.jsonc 和 .env.production 還原成這次修改前的狀態。如果已進入遠端部署，或部署後的健康檢查失敗，就不能認為網域和遠端版本也已自動還原。
這時請檢查：
- 本機設定中的 Custom Domain 與
VITE_SITE_URL。 - Cloudflare Worker 目前的網域與已部署版本。
- DNS、HTTPS 和首頁回應是否正常。
- 是否因舊網站網址或代理設定，被重新導向其他 Origin。
修復後，再執行適合的部署操作。domain:set 只檢查首頁，不會執行完整的 verify、資料庫遷移和 KV 同步。如果同時修改了業務程式碼或內容，應先依更新流程發布。
四、核對正式回呼位址
下列網址以 .env.production 中的正式 Origin 為準，不包含語言前綴：
| 服務 | 應填寫的網址或主機 |
|---|---|
| GitHub OAuth Callback URL | https://app.example.com/api/auth/oauth2/github |
| Google Authorized JavaScript origins | https://app.example.com |
| Google Authorized redirect URIs | https://app.example.com/api/auth/oauth2/google |
| Stripe Webhook | https://app.example.com/api/webhooks/stripe |
| Turnstile 允許的主機 | app.example.com |
不要在 OAuth Callback 前面加上 /zh-Hans、/en 或登入頁面路徑，也不要將付款成功後的重新導向頁面當成 Webhook。
GitHub 與 Google 登入
沿用前面 GitHub OAuth 和 Google OAuth 的設定，核對正式環境的 Client ID、Client Secret 與回呼是否屬於同一個應用程式。
本機與正式環境如何保留回呼，必須依供應商和應用程式類型分別處理，不能假設所有 OAuth 應用程式都支援在同一個欄位填入多個網址。尤其是曾為本機開發另外建立應用程式時，不要只修改回呼，卻繼續使用另一組 Client ID。
啟用 Google One Tap 後，除了普通 OAuth 登入，也要單獨檢查正式網站上的 One Tap。它依賴瀏覽器環境和來源設定，普通登入成功無法取代這項檢查。
Stripe Webhook
如果已依 Stripe 付款教學建立正式 Webhook，核對網址和目前端點的簽章金鑰即可，不要再建立重複端點。
如果尚未建立，可以在 .env.production 中準備正式的 STRIPE_SECRET_KEY 和 VITE_SITE_URL，接著執行：
npm run webhook:stripe:prod指令碼會檢查正式金鑰模式，讓你確認網址、事件和 API 版本，建立新的 Webhook 端點，並將回傳的簽章金鑰寫入 .env.production。預設事件清單與版本由 scripts/stripe/webhook.ts 維護，通常保留專案提供的預設選項即可。
這個指令執行的是建立操作，不會自動更新既有端點。建立完成後，還需要執行：
npm run deploy:update這次更新會讓 Worker 使用新的 STRIPE_WEBHOOK_SECRET。Webhook 切換期間，可能出現尚未同步的事件，應在設定生效後檢查失敗的投遞，並確認重試處理結果。
STRIPE_CONNECTION_ID 用來識別付款連線，確定後應保持穩定。切換網域通常不需要同時更換它，否則同一個付款平台物件可能被當成另一個連線的資料處理。
Turnstile
在正式 Widget 的主機清單中加入 app.example.com，並確認 .env.production 使用該 Widget 對應的 Site Key 和 Secret Key。
如果已在執行 domain:set 前更新金鑰，該指令會一併部署。如果綁定網域後才替換金鑰，請再執行一次 deploy:update。只更新平台允許的主機，而沒有修改應用程式設定時，不必為這一項重新發布程式碼。
電子郵件
寄件網域與網站網域可以不同。例如網站使用 app.example.com，郵件透過已驗證的 mail.example.com 寄出。重點是目前供應商允許設定的寄件者地址，而且郵件中的網站連結指向正式 Origin。
domain:set 不會替你驗證 Resend 網域，也不會變更郵件接收規則。部署完成後，請實際寄送註冊驗證和密碼重設郵件，檢查寄件者名稱、送達情況和內文連結。
五、處理 www、workers.dev 與檔案網域
綁定 example.com 不會自動綁定 www.example.com。如果需要讓兩者都能輸入，應先決定哪個是正式入口，再為另一個網址設定保留路徑和查詢參數的重新導向。實際操作請見網域設定中的 www 說明。
目前範本預設為 workers_dev: true，domain:set 不會自動將它關閉。正式網域穩定後，如果不再需要這個入口，可以在 wrangler.jsonc 中改成 false，再執行 deploy:update。關閉前，請先確認沒有登入回呼、Webhook 或業務呼叫仍依賴舊網址。
如果保留 workers.dev，不要同時將它當成另一個正式 Origin 使用。目前應用程式會依允許的主機與 VITE_SITE_URL 處理請求，舊網址的重新導向也無法取代供應商後台的回呼遷移。
R2 檔案網域是獨立設定。需要公開檔案網址時，請依檔案儲存設定 publicBaseUrl 和 Bucket 的公開存取。將 publicBaseUrl 改成 false，只會影響應用程式產生的網址，不會自動關閉 Cloudflare 中已開放的 R2 網域。
六、完成切換驗收
開啟新的瀏覽器工作階段，依下列順序檢查：
- 首頁、文件和主要業務頁面使用正式 HTTPS 網址。
- 頁面內部連結、Canonical、Open Graph 等沒有指向舊網域。
- 密碼登入和已啟用的 OAuth 登入能返回正式網站。
- Turnstile 能依預期完成，網路請求沒有網域不符的錯誤。
- 郵件中的驗證和重設連結使用正式網域。
- Stripe 端點收到預期事件，Worker 能驗證簽章並更新業務狀態。
- 舊入口的存取結果符合預期，沒有循環重新導向。
網域變更後，不要假設瀏覽器會自動將舊網域上的登入 Cookie 帶到新網域，應重新登入驗證。
完成後，進入上線驗收與日常維護。