Cloudflare Workers

将 Workers 应用接入 D1、R2 和 Cloudflare 邮件，依次完成资源创建、配置、预览和部署。

开始前准备

安装项目依赖，准备具备 Workers/D1/R2/Email Sending 权限的 Cloudflare 账号和部署域名。选择 apps/web-cloudflare，命令在仓库根目录运行。需要先体验本地时，完成快速开始。使用全新远端数据库；已有产品先准备升级方案。

1. 准备账号与资源

在仓库根目录安装依赖，使用应用自带 Wrangler，无需全局安装：

pnpm install
pnpm --filter @musemvp/cloudflare exec wrangler login
pnpm --filter @musemvp/cloudflare exec wrangler d1 create <your-database-name>
pnpm --filter @musemvp/cloudflare exec wrangler r2 bucket create <your-bucket-name>

账号需要能使用 Workers、D1、R2 和 Email Sending。额度、权限、CPU 与 bundle 限制以平台当前规则为准；模板不保证所有功能零费用。

2. 配置绑定

编辑 apps/web-cloudflare/wrangler.jsonc。不要复用模板演示账号的资源 ID、域名或名称。

{
  "name": "your-app",
  "main": ".open-next/worker.js",
  "compatibility_date": "2026-09-30",
  "compatibility_flags": ["nodejs_compat", "global_fetch_strictly_public"],
  "workers_dev": false,
  "preview_urls": false,
  "routes": [{ "pattern": "app.example.com", "custom_domain": true }],
  "assets": { "binding": "ASSETS", "directory": ".open-next/assets" },
  "d1_databases": [{
    "binding": "DB",
    "database_name": "your-database-name",
    "database_id": "<your-d1-id>",
    "migrations_dir": "../../packages/db/migrations-d1"
  }],
  "r2_buckets": [{ "binding": "R2_BUCKET", "bucket_name": "your-bucket-name" }]
}

这是绑定片段；保留模板其余必要配置。DB 与 R2_BUCKET 的大小写必须一致。当前 scripts/d1-migrations.ts 的 databaseName 也是演示名称，派生产品必须同步改成自己的 D1 名称后再执行数据库命令。

3. 初始化本地环境

pnpm muse:init --yes --app cloudflare
pnpm db:seed:d1
pnpm cf:typegen
pnpm dev:cf

初始化写入 apps/web-cloudflare/.env.local 和 .dev.vars，生成认证/订阅签名密钥并应用本地 D1 迁移。它不会创建远端 D1 或 R2。默认本地账号为 [email protected] 与 [email protected]，密码取 MUSE_SEED_PASSWORD（默认 musemvp）。只用于开发。

pnpm dev:cf 是 Next 开发模式；要检查真实 Worker 打包和绑定，再用 pnpm cf:preview。修改 .env.local 后也要同步 .dev.vars，不要假定两文件会持续自动同步。

4. 配置生产邮件、认证和支付

按环境变量为 Worker 配置服务端密钥。至少设置认证密钥、订阅签名密钥和 Cloudflare 邮件凭据；按实际启用功能配置 OAuth、Turnstile 与支付网关。生产 MAIL_PROVIDER=cloudflare。

构建时设置 NEXT_PUBLIC_SITE_URL=https://app.example.com 和其他实际使用的 NEXT_PUBLIC_*。仅在 Worker 运行时修改公开变量不会更新已经内联的客户端 URL。

可用应用作用域的命令逐项写入密钥：

pnpm --filter @musemvp/cloudflare exec wrangler secret put BETTER_AUTH_SECRET
pnpm --filter @musemvp/cloudflare exec wrangler secret put NEWSLETTER_TOKEN_SECRET
pnpm --filter @musemvp/cloudflare exec wrangler secret put CLOUDFLARE_API_TOKEN

其余变量在部署平台配置，或通过经过筛选的密钥文件导入。不要整份上传本地 seed 与开发配置。

5. 迁移并部署

pnpm db:migrate:d1:status
pnpm db:migrate:d1:remote
pnpm db:migrate:d1:status --strict
pnpm cf:deploy

远端迁移脚本先导出备份，在本地克隆上应用并检查迁移，再应用远端。备份含用户数据，妥善保管。cf:deploy 会先执行严格 D1 状态检查，存在待执行迁移则停止，而不是自动修改生产数据库。

OpenNext 配置使用 webpack 构建；pnpm build:cf 是应用 Next 构建，cf:preview / cf:deploy 还会构建 Worker。保留锁文件和当前 OpenNext 补丁，直到明确验证新版本不再需要。绑定变化后重新执行 pnpm cf:typegen，不要手写 cloudflare-env.d.ts。

确认结果

运行 pnpm cf:preview，打开它给出的 URL 检查构建后的 Worker 和本地绑定。执行 pnpm cf:deploy 后打开配置的 HTTPS 域名，检查远端 D1 状态。通过生产账号流程验证登录、真实邮件和自己的头像上传/下载，不在远端创建默认开发 seed 账号。最后完成上线检查清单。

常见问题

登录/退出、OTP 与 OAuth 回调使用实际 HTTPS 域名验证。
头像 PUT/GET 经同源 /files/avatars/* 进入 R2；检查会话、用户前缀与绑定。
支付使用沙盒，确认真实签名 Webhook 更新合约与权益。
D1 binding DB is required / R2 binding R2_BUCKET is required：检查绑定，而不是添加 DATABASE_URL 或 S3 密钥。
D1 不支持包中的交互式 transaction()；多语句写入需走支持的 batch()，见数据库配置。

本页目录