准备生产配置与密钥
整理应用配置、正式服务凭据和环境文件，理解部署脚本如何上传变量与 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 密钥，按存储功能中实际使用的接口准备即可。
默认邮件提供商是 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 检查配置与身份，不会替你向用户发送邮件或完成支付。
不要把完整环境文件粘贴进工单、聊天记录或版本库。需要排查时，记录变量名称、所属环境和是否已配置即可。
下一步：管理生产数据库与内容。