準備正式環境設定與金鑰
整理應用程式設定、正式服務的驗證資訊和環境檔案，了解部署指令碼如何上傳變數與 Secret。
上線前，要將開發階段的品牌、服務網址和測試驗證資訊整理成正式環境設定。這裡延續前面品牌與專案設定和選用服務的操作，重點是確認最終部署使用哪一組值。
一、先分清楚設定放在哪裡
| 檔案或位置 | 儲存的內容 | 修改後如何生效 |
|---|---|---|
config/base.ts | 品牌、寄件者、客服信箱、管理員電子郵件地址等 | 建置並部署 |
config/deploy.ts | 功能開關、郵件供應商、額外允許的網域等 | 建置並部署 |
config/products.ts | 產品、Plan、Price ID 和購買權益 | 建置並部署 |
config/i18n.ts、locales/ | 支援的語言和介面文案 | 建置並部署 |
wrangler.jsonc | 帳戶、Worker 名稱、資源繫結、網域和排程規則 | 透過部署流程更新 |
.env | 本機開發環境的值 | 重新啟動本機開發服務 |
.env.production | 遠端部署的環境值與應用程式金鑰 | 執行部署或更新指令 |
| 第三方服務後台 | 寄件網域、OAuth 回呼、Webhook 和允許的主機 | 在對應平台儲存，若本機金鑰也有變更，再重新部署 |
example.vars 是變數清單，並不是可以直接用來上線的完整設定。只填寫實際啟用的服務，不必為了消除所有提示而申請暫時用不到的供應商服務。
第一次執行 deploy:init 時，會收集必要資訊並建立或補充 .env.production。如果已事先手動準備檔案，指令碼會讀取其中既有的值。
二、保留既有的 SAAS_SECRET
目前部署指令碼要求 .env 和 .env.production 中的 SAAS_SECRET 都存在，而且完全一致。首次部署時，如果正式環境檔案缺少這個值，會使用本機專案既有的值，後續更新與網域切換也會檢查一致性。
因此，不要在上線當天，臨時為這個專案產生另一把正式環境金鑰，也不要為了通過檢查而任意替換兩份檔案中的值。這把金鑰用於處理既有的加密資料，替換後可能導致歷史資料無法讀取。
如果建立新專案時還沒產生金鑰，請回到本機開發完成初始化。獨立的新專案可以有自己的金鑰，既有專案的金鑰輪替則需要專門的資料遷移方案。
這項要求不代表其他服務都應共用測試驗證資訊。Stripe、Turnstile、OAuth 等仍應依各自的環境和網站設定。
三、確認正式服務設定
| 服務 | 需要檢查的值 | 上線要求 |
|---|---|---|
| Turnstile | CLOUDFLARE_TURNSTILE_SITE_KEY、CLOUDFLARE_TURNSTILE_SECRET_KEY | 兩者屬於同一個正式 Widget，主機清單包含正式網站 |
| Resend | RESEND_API_KEY | 目前的寄件網域已驗證，Key 具有寄送權限 |
| Stripe | STRIPE_CONNECTION_ID、STRIPE_SECRET_KEY、STRIPE_WEBHOOK_SECRET | 正式收款使用互相對應的正式設定，Price ID 也屬於相同模式 |
| GitHub OAuth | GITHUB_CLIENT_ID、GITHUB_CLIENT_SECRET | 屬於已設定正式回呼的應用程式 |
| Google OAuth | GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET | 來源、回呼和應用程式發布狀態符合實際使用需求 |
| R2 簽署存取 | R2_ACCOUNT_ID、R2_ACCESS_KEY_ID、R2_SECRET_ACCESS_KEY | 只在使用預先簽署的上傳或下載等 API 功能時設定 |
| 外部通知 | config/notifications.ts 啟用的目標所引用的變數 | 目標網址、權杖與實際接收管道一致 |
一般的 R2 繫結讀寫，不代表一定要設定 R2 API 金鑰，依檔案儲存功能中實際使用的 API 準備即可。
預設郵件供應商是 Resend。如果選擇 Cloudflare 郵件服務，需要帳戶具備對應功能、EMAIL 繫結，以及允許的寄件者，不能只修改設定中的供應商名稱。兩種方式的準備步驟請見電子郵件。
測試用 Turnstile 金鑰可用於初步驗證部署是否正常運作，正式開放前應換成實際設定。指令碼主要檢查是否已填寫，不會替你判斷輸入的是否為測試值。
四、整理網站網址
首次部署使用指令碼產生的 workers.dev 網址。綁定正式網域時，domain:set 會將 .env.production 的 VITE_SITE_URL 更新為正式的 HTTPS 來源網址，例如：
VITE_SITE_URL="https://app.example.com"這裡只展示單一欄位，並不是完整的環境檔案。網站網址不要包含 /docs 等路徑、查詢參數或片段。
正式環境建置會使用這個網址產生網站相關內容，執行階段也依賴它。如果只修改 Cloudflare 主控台中的值，卻沒有同步本機設定並重新部署，可能造成頁面連結與執行階段網址不一致。
config/deploy.ts 的 hosts 用於額外允許的主機，VITE_SITE_URL 中的主機已自動允許，通常不必重複加入。trustedOrigins 則是跨來源請求的信任設定，不是 DNS 綁定或 OAuth 回呼清單。同源網站上線時，不必為此加入萬用字元。
網域、根網域與 www、檔案網域的處理方式，請見正式網域與第三方回呼。
五、了解變數如何上傳
部署指令碼讀取 .env.production 後，會依專案維護的公開欄位清單處理：
- 公開欄位作為 Worker 變數傳入，例如
VITE_SITE_URL、Turnstile Site Key 和 OAuth Client ID。 - 其他非空白欄位作為 Secret 隨部署上傳，例如
SAAS_SECRET、OAuth Client Secret 和 Stripe 簽章金鑰。 - 空白值會略過，不會自動刪除遠端既有的 Secret。
判斷公開欄位時，不是只看有沒有 VITE_ 前綴。也不要自行為密碼、存取權杖或簽章金鑰加上 VITE_ 前綴，這類變數可能進入用戶端建置產物。
Cloudflare 部署使用的 CLOUDFLARE_API_TOKEN 等驗證資訊，不能放進 .env.production，指令碼會拒絕將它們當成應用程式環境部署。互動式開發可使用 Wrangler 登入，自動部署則在執行環境中管理驗證資訊。
日常修改以本機的正式環境設定為準，再執行 npm run deploy:update。如果緊急處理時只修改遠端 Secret，後續部署可能再次覆寫它，應同步更新受保護的設定紀錄。
停用服務或撤銷驗證資訊時，只清空本機的值還不夠。請先處理功能開關和呼叫端，再到供應商平台撤銷驗證資訊，並視需要移除遠端 Secret，避免誤以為空字串就代表已完成清理。
六、發布前檢查產品內容
準備設定時，一併檢查：
- 網站名稱、Logo、客服信箱、寄件者和法律頁面都已換成自己的內容。
adminEmails是能接收郵件並完成驗證的地址。- 所有銷售中的 Plan 都綁定實際 Price，金額、幣別、週期和權益說明一致。
- 聯盟行銷分潤比例、優惠活動和贈送權益符合本次發布計畫。
- 文件、部落格和語言選單只展示準備發布的內容，不將範本測試文章當成正式說明中心。
- 業務專用的外部服務已部署，主網站的繫結和驗證資訊已核對一致。
第一版若不收款，可以暫時略過 Stripe，但購買入口和產品說明也應與這項決定一致。保留占位 Price 的方案，不能作為實際可購買的方案展示。
七、執行設定檢查
尚未進行首次部署時，執行：
npm run doctor
npm run verify已初始化遠端專案時，額外執行：
npm run doctor:remoteverify 包含程式碼規範、型別、測試和正式環境建置。doctor:remote 檢查設定與身分，不會替你寄送郵件給使用者或完成付款。
不要將完整的環境檔案貼到客服案件、聊天紀錄或版本控制儲存庫中。需要排查時，記錄變數名稱、所屬環境和是否已設定即可。
下一步：管理正式環境資料庫與內容。