選用服務
了解 Saavo 在本機開發和首次部署時需要哪些外部服務，再依產品需求串接付款、登入、分析和通知功能。
Saavo 範本預留了不少第三方服務的串接設定，但不需要在建立專案前全部註冊。本章會集中整理這些服務的註冊與串接方式，目前先說明何時需要設定，以及設定應放在哪裡。
各階段需要準備什麼
| 階段 | 需要處理的外部服務 |
|---|---|
| 建立專案 | 不需要新增第三方帳號，使用範本內附的 Turnstile 測試金鑰 |
| 本機開發 | 只串接正在開發的功能，Stripe、OAuth、分析和通知設定都可以先留白 |
| 首次部署 | 依 deploy:init 提示準備 Turnstile 和目前郵件服務需要的設定。如果還沒有正式網域，可以使用 Turnstile 測試金鑰，Stripe 也可以先略過 |
| 上線前 | 將 Turnstile 換成正式網域對應的實際金鑰，並檢查 OAuth 回呼、付款 Webhook，以及其他已啟用服務的正式環境設定 |
建立專案時不用準備正式環境設定
使用 Saavo CLI 建立專案：
npx saavo-cli@latest create my-project同意初始化本機環境後，CLI 會安裝相依套件，並呼叫範本自己的 saavo:init。這個流程會建立 .env、產生本機的 SAAS_SECRET、保留 Turnstile 測試金鑰，並初始化本機資料庫。
如果建立專案時略過了本機初始化，請進入專案目錄後執行：
npm install
npm run saavo:init這時不需要準備 Resend、Stripe、GitHub 或 Google 等服務在正式環境使用的金鑰。先執行 npm run dev，確認專案能正常啟動，再決定要串接哪些服務。
本機開發依功能需求串接
本機的 .env 只用於開發環境。暫時用不到的變數請保持空字串，不要為了填滿檔案而隨意填入占位值。
| 正在開發的功能 | 需要準備的項目 | 未設定時的影響 |
|---|---|---|
| 在正式環境寄送郵件 | Resend API Key，或改用 Cloudflare Email | 註冊郵件、驗證碼和密碼重設郵件無法送達 |
| Stripe 購買流程 | Stripe 測試金鑰、連線識別碼、Webhook Secret 和實際的測試 Price ID | 可以顯示定價內容，但無法完成 Checkout |
| GitHub 登入 | GitHub OAuth App 的 Client ID 和 Client Secret | 不會啟用 GitHub 登入入口 |
| Google 登入 | Google OAuth 用戶端的 Client ID 和 Client Secret | 不會啟用 Google 登入和 One Tap |
| 第三方分析或廣告 | 所選平台提供的網站 ID、Token 等設定 | 不會載入對應的指令碼 |
| 外部通知 | Webhook、Bot Token 或簽章金鑰 | 不會將事件傳送到外部管道 |
一般檔案上傳不需要 R2_ACCOUNT_ID、R2_ACCESS_KEY_ID 和 R2_SECRET_ACCESS_KEY。範本透過 Worker 的 MAIN_R2 繫結存取儲存貯體。只有自行串接 R2 S3 API，或透過簽署函式產生臨時上傳、下載連結等情境，才需要準備這組驗證資訊，詳見檔案儲存。
首次部署時統一收集設定
準備第一次部署到 Cloudflare 時，執行：
npx wrangler login
npm run deploy:initdeploy:init 會選擇 Cloudflare 帳戶、確認 Worker 和資源名稱、收集正式環境設定，並建立 .env.production。依範本目前的預設設定，主要需要處理以下項目：
- Turnstile：預設啟用，Site Key 和 Secret Key 都不能留白。首次部署到
workers.dev時，可以輸入 Cloudflare 官方測試金鑰。 - 郵件：預設使用 Resend，因此需要
RESEND_API_KEY。如果已改用 Cloudflare Email，部署指令碼會設定EMAIL繫結。 - Stripe：部署時會詢問是否現在設定，可以先略過。
- OAuth、分析和通知：尚未啟用的項目繼續留白，之後再寫入
.env.production，並執行npm run deploy:update。
本機的 .env 和正式環境的 .env.production 各自管理一個環境，不要互相覆寫：
| 檔案 | 用途 | Turnstile |
|---|---|---|
.env | 本機開發 | 保留 Cloudflare 測試金鑰 |
.env.production | 遠端部署 | 首次驗證可暫用測試金鑰，正式開放前換成實際 Widget 的金鑰 |
.env.production 已列入 Git 忽略清單。Saavo 部署指令碼會將其中的公開值同步為 Worker Variables，機密值則同步為 Secrets，不要繞過這個流程，另外維護一組遠端設定。
常用設定位置
第三方服務通常同時需要功能設定和環境變數。只填金鑰不一定會自動切換服務，只修改設定也無法憑空取得存取權。
| 服務 | 功能設定 | 本機與正式環境設定 |
|---|---|---|
| Turnstile | config/deploy.ts → auth.useTurnstile | CLOUDFLARE_TURNSTILE_* |
| 郵件 | config/deploy.ts → emailProvider | RESEND_API_KEY 或 EMAIL 繫結 |
| 付款 | config/payment.ts、config/products.ts | STRIPE_* |
| OAuth 登入 | config/deploy.ts → auth / ui | GITHUB_*、GOOGLE_* |
| 第三方分析 | config/analytics.ts | 各平台提供的 ID、Token 或網站識別碼 |
| 廣告 | config/ads.ts | 廣告平台提供的網站 ID |
| 通知 | config/notifications.ts | Webhook、Bot Token 或簽章金鑰 |
修改 .env 後，需重新啟動 npm run dev。修改 .env.production 後，已完成首次部署的專案請執行：
npm run deploy:update現有教學
- 設定 Turnstile：先完成首次部署，再為正式網域建立 Widget、替換金鑰，並驗證用戶端與伺服器端的流程。
- 網域設定：直接在 Cloudflare 註冊網域，或將第三方註冊商購買的網域加入 Cloudflare，再設定網站、郵件和 R2 自訂網域。
- 設定 Resend：完成網域驗證、建立權限受限的 API Key，並啟用 Saavo 的註冊、密碼重設和安全通知郵件。
- 設定 GitHub OAuth：建立 OAuth App，登記本機與正式環境的回呼網址，並設定 Client ID 和 Client Secret。
- 設定 Google OAuth：設定 Google Auth Platform 和 Web application 用戶端，啟用一般 Google 登入，以及選用的 One Tap。
後續教學規劃
後續會依以下分類持續新增獨立頁面。沒有連結的項目表示尚未補上教學，不代表範本不支援。
- 郵件：Cloudflare Email
- 付款：Stripe
- Cloudflare 功能：R2 API Token 與簽章下載
- 分析與廣告：Google Analytics、Microsoft Clarity、Cloudflare Web Analytics、Umami、Plausible、PostHog、Google AdSense 等
- 通知管道：Slack、Discord、Telegram、Microsoft Teams、飛書、釘釘、企業微信和通用 Webhook
example.vars 中仍保留 PADDLE_* 變數，但目前的 config/payment.ts 只允許使用 Stripe。現階段不需要因為看到這些變數就註冊 Paddle，等範本正式支援後，再補上對應教學。
如果現在只是準備開發環境，可以繼續閱讀建立專案。等需要部署時，再回到本章設定正式服務。