Saavo

首次部署

通过 deploy:init 创建 Cloudflare 资源、写入生产配置并部署到 workers.dev。

首次部署不需要手工创建 D1、KV、R2 Bucket 和 Queue，也不要自己把资源 ID 填进 wrangler.jsonc。项目提供的 deploy:init 会检查目标账户和资源名称，在你确认后完成整个初始化过程。

部署前准备

开始前确认下面几项已经就绪：

  • Cloudflare 账号已验证，并且准备部署的账户已经开通 R2；
  • 已决定 Turnstile 暂时使用官方测试密钥，还是使用正式 Widget 的 Site Key 和 Secret Key；
  • 默认邮件服务仍为 Resend 时，已经准备好 Resend API Key；
  • 已确定发件人邮箱和支持邮箱；
  • 如果准备同时启用 Stripe，已经准备好连接标识、Secret Key 和 Webhook Secret。

如果目前只有 Cloudflare 分配的 workers.dev 地址，可以先使用模板自带的 Turnstile 测试密钥。确定正式域名后再创建 Widget、替换 .env.production 中的密钥并重新部署。完整过程见配置 Turnstile。Stripe、OAuth 和通知服务没有启用时不用为了部署而临时注册。

远程配置写入 .env.production

.env 继续用于本地开发。Turnstile、Resend 和 Stripe 的远程环境配置在 deploy:init 交互过程中输入，并保存到 .env.production。Turnstile 测试密钥也应填在这里，不能因为它是测试值就让远程部署去读取本地 .env。这两个文件都不会提交到 Git。

登录 Cloudflare

在项目根目录执行：

npx wrangler login

浏览器会打开 Cloudflare 授权页。

Cloudflare 授权

确认登录用户能够访问准备部署的账户，再允许 Wrangler 访问。授权完成后可以用下面的命令核对：

npx wrangler whoami

控制台会输出当前授权的账号信息和权限列表：

wrangler whoami

如果能看到多个账户，记住这次项目应该使用哪一个。deploy:init 会在终端中让你选择。

运行首次部署

执行：

npm run deploy:init

按照终端提示依次完成：

  1. 选择 Cloudflare 账户；
  2. 确认 Worker 名称以及由它派生的资源名称；
  3. 输入成对的 Turnstile Site Key 和 Secret Key；首次验证部署可以使用官方测试组合；
  4. 确认发件人邮箱和支持邮箱；
  5. 默认使用 Resend 时输入 RESEND_API_KEY；
  6. 选择是否现在配置 Stripe；
  7. 确认写入 .env.production；
  8. 查看准备创建的 Worker、D1、KV、R2 和 Queue，确认后开始部署。

首次部署

脚本不会复用或覆盖同名的现有资源。检测到名称冲突时，它会停止并说明冲突位置；确认资源归属之前，不要为了继续执行而随意删除 Cloudflare 账户中的内容。

确认后，脚本会自动完成类型检查和生产构建，创建并绑定 Cloudflare 资源，部署 Worker，迁移远程数据库，同步 KV，最后检查首页及已启用的内容页面。

部署成功后，终端会打印类似下面的地址：

https://my-project.<你的-workers.dev-子域>.workers.dev

首次部署成功

打开这个地址，确认首页和 /docs 可以访问。

首次访问 docs 页面

使用官方测试组合时，可以继续验证注册等表单是否接通，但它不会识别真实机器人；使用正式 Widget 时，还要确认其 Hostname 列表包含浏览器地址栏中的实际主机名。

中途退出后怎么继续

如果在配置检查阶段退出，且尚未创建远程资源，修正终端指出的问题后可以重新运行：

npm run deploy:init

如果 Worker 或部分资源已经创建，则先检查远程状态和本地绑定，不要直接重复初始化。数据库迁移、KV 同步或健康检查阶段的失败，按部署中断处理继续。

成功完成首次部署以后，项目已经记录 Cloudflare 账户、资源 ID 和生产环境。后续修改代码或 .env.production 时改用：

npm run deploy:update

不要在已经初始化的项目上反复运行 deploy:init，也不要绕过项目脚本单独维护另一套 Wrangler Secrets。

使用自定义域名

首次部署必须先在 workers.dev 上完成。准备切换到 Cloudflare 中已经管理的正式域名时运行：

npm run domain:set -- https://app.example.com

命令会更新站点地址和 Worker Custom Domain，重新验证并部署项目。准备切换域名前，建议先在 Turnstile 创建正式 Widget，并把真实密钥写入 .env.production，这样 domain:set 会连同新密钥一起部署。如果先绑定了域名，之后才替换密钥，则修改 .env.production 后再运行 npm run deploy:update。

域名切换完成后，还要分别处理 Resend 中用于发送邮件的域名、OAuth 回调地址和 Stripe Webhook。终端会打印当前项目对应的回调地址，逐项复制到各服务后台即可。

到这里，项目已经完成从 Saavo 模板到 Cloudflare 的第一次完整部署。接下来进入实践，开始修改产品内容；准备面向真实用户时，再按照部署上线完成正式检查。