可选服务
了解 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 Binding 访问存储桶；这三个变量主要用于发行包签名下载等直接访问 R2 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，则由部署脚本配置EMAILBinding； - 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 Binding |
| 支付 | 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；等模板正式支持 Paddle 后，再补充对应教程。
如果现在只是准备开发环境，可以继续阅读创建项目。需要部署时，再回到本章处理正式服务。