Cloudflare Workers

使用 OpenNext.js 将 NEXTDEVKIT 部署到 Cloudflare Workers 以获得全球边缘性能

将您的 NEXTDEVKIT 应用程序部署到 Cloudflare Workers，这是最具成本效益的全球边缘部署平台。Cloudflare Workers 提供卓越的性能，内置 CDN 和全球超低延迟。

🎯 为什么选择 Cloudflare Workers

最具成本效益：按请求付费，极其实惠
全球边缘网络：部署到全球 300+ 个位置，约 10ms 冷启动
内置 CDN：包含全球内容分发网络
零出站费用：出站流量无带宽费用
慷慨的免费层：免费计划每天 100,000 个请求

📋 先决条件

在部署您的 NEXTDEVKIT 项目之前，确保您拥有：

Cloudflare 账户：如果您没有账户，请在此注册
Cloudflare Workers 标准计划（5 美元/月）：由于免费计划的 worker 大小限制为 3 MB，您需要升级到标准计划。
环境变量：准备好生产环境变量（参见环境指南）

🚀 部署步骤

第 1 步：配置环境变量

请参考环境指南了解详细的环境变量。

复制 .env.example 到 .env.production 并更新环境变量。

第 2 步：配置 Wrangler 配置

更新项目根目录中的 wrangler.jsonc 文件。

{
    "account_id": "your-account-id",
    "name": "your-worker-name",
}

如果您更改了 worker 名称，还需要更新 wrangler.jsonc 服务绑定到新的 worker 名称。

"services": [
    {
        "binding": "WORKER_SELF_REFERENCE",
        "service": "your-worker-name"
    }
]

第 3 步：配置 D1 数据库

在生产环境中为您的 NEXTDEVKIT 项目创建新的 D1 数据库：

# 创建 D1 数据库
pnpm wrangler d1 create prod-d1-tutorial

预期输出：

   ✅ Successfully created DB 'prod-d1-tutorial' in region WEUR
   Created your new D1 database.

   {
     "d1_databases": [
       {
         "binding": "DB",
         "database_name": "prod-d1-tutorial",
         "database_id": "<unique-ID-for-your-database>"
       }
     ]
   }

第 4 步：创建 KV 命名空间

为缓存和会话存储创建 KV 命名空间：

# 创建 KV 命名空间
pnpm wrangler kv namespace create nextdevkit-cloudflare-template-kv

预期输出：

🌀 Creating namespace with title "USERS_NOTIFICATION_CONFIG"
✨ Success!
Add the following to your configuration file in your kv_namespaces array:
{
  "kv_namespaces": [
    {
      "binding": "USERS_NOTIFICATION_CONFIG",
      "id": "<BINDING_ID>"
    }
  ]
}

第 5 步：配置 wrangler.jsonc

使用数据库和 KV 配置更新您的 wrangler.jsonc 文件：

// wrangler.jsonc
{
  "name": "nextdevkit-cloudflare-template",
  "compatibility_flags": ["nodejs_compat"],
  
  // D1 数据库配置
  "d1_databases": [
    {
      "binding": "NEXT_TAG_CACHE_D1",
      "database_name": "your-database-name",
      "database_id": "<unique-ID-for-your-database>",
      "migrations_dir": "drizzle"
    }
  ],
  
  // KV 命名空间配置
  "kv_namespaces": [
    {
      "binding": "NEXT_INC_CACHE_KV",
      "id": "<unique-ID-for-your-namespace>"
    }
  ],
}

请不要更改 d1_databases 和 kv_namespaces 的默认绑定名称，如果您想将名称如 NEXT_TAG_CACHE_D1 更改为 DB，您需要更新代码以使用新名称。

src/database/client.ts

const { env } = await getCloudflareContext({ async: true });

if (!env.NEXT_TAG_CACHE_D1) {
  throw new Error("D1 database not found");
}

dbInstance = drizzle(env.NEXT_TAG_CACHE_D1, { schema, logger: true });

return dbInstance;

您需要在全局范围内搜索名称以找到绑定名称，并更新代码以使用新名称。

第 6 步：在本地环境中初始化 D1 数据库

在本地开发环境中初始化 D1 数据库：

# 创建本地 D1 数据库
npx wrangler d1 execute your-database-name --local --command='SELECT 1'

参考：有关详细的数据库设置，请参见数据库指南。

第 7 步：部署到 Cloudflare

pnpm install

# 登录到您的 Cloudflare 账户
pnpm wrangler login

# 检查您的账户 ID
pnpm wrangler whoami

# 构建项目
pnpm run build:prod

# 数据库迁移
pnpm run db:migrate:prod

# 部署到生产环境
pnpm run deploy

🌐 重要：域配置

场景 1：您已有域名（例如 workers.nextdevkit.com）

如果您已拥有要使用的域名：

设置环境变量为您的最终域名：

BETTER_AUTH_URL="https://workers.nextdevkit.com"
NEXT_PUBLIC_APP_URL="https://workers.nextdevkit.com"

使用这些设置部署应用程序
在 Cloudflare 仪表板中绑定您的域名：
- 在 Cloudflare 仪表板中转到您的 worker
- 导航到"Settings" → "Domains & Routes"
- 在"Custom Domain"下添加您的自定义域名

场景 2：您还没有域名

如果您没有域名并且想使用 Cloudflare 的自动生成域名：

使用占位符值进行初始部署：

BETTER_AUTH_URL="https://placeholder.workers.dev"
NEXT_PUBLIC_APP_URL="https://placeholder.workers.dev"

部署应用程序 - Cloudflare 将自动为您分配一个像 your-worker-name.your-subdomain.workers.dev 的域名

使用分配的域名更新环境变量：

BETTER_AUTH_URL="https://your-worker-name.your-subdomain.workers.dev"
NEXT_PUBLIC_APP_URL="https://your-worker-name.your-subdomain.workers.dev"

使用正确的域名重新部署应用程序

⚠️ 重要：如果您配置了错误的域名，登录重定向将无法正常工作，因为身份验证系统需要正确的域名 URL。

🔧 数据库迁移

运行迁移

# 生成迁移文件
pnpm run db:generate

# 将迁移应用到开发环境
pnpm run db:migrate:dev

# 将迁移应用到生产环境
pnpm run db:migrate:prod

在本地机器上运行 Drizzle Studio

npx wrangler d1 execute your-database-name --local --command='SELECT 1'

pnpm run db:studio

数据库管理

# 清理 D1 缓存
pnpm run d1:cache:clean

# 管理 KV 存储
pnpm run list:kv
pnpm run delete:kv

已知问题

在本地环境中，运行 pnpm dev 会抛出以下错误：

✓ Compiled middleware in 256ms
▲ [WARNING]                             You have defined bindings to the following internal Durable Objects:

                                - {"name":"NEXT_CACHE_DO_QUEUE","class_name":"DOQueueHandler"}
                                These will not work in local development, but they should work in production.
  
                                If you want to develop these locally, you can define your DO in a separate Worker, with a
  separate configuration file.
                                For detailed instructions, refer to the Durable Objects section here:
  https://developers.cloudflare.com/workers/wrangler/api#supported-bindings


 ✓ Ready in 1478ms
▲ [WARNING]                             You have defined bindings to the following internal Durable Objects:

                                - {"name":"NEXT_CACHE_DO_QUEUE","class_name":"DOQueueHandler"}
                                These will not work in local development, but they should work in production.
  
                                If you want to develop these locally, you can define your DO in a separate Worker, with a
  separate configuration file.
                                For detailed instructions, refer to the Durable Objects section here:
  https://developers.cloudflare.com/workers/wrangler/api#supported-bindings


workerd/server/server.c++:1873: warning: A DurableObjectNamespace in the config referenced the class "DOQueueHandler", but no such Durable Object class is exported from the worker. Please make sure the class name matches, it is exported, and the class extends 'DurableObject'. Attempts to call to this Durable Object class will fail at runtime, but historically this was not a startup-time error. Future versions of workerd may make this a startup-time error.
workerd/server/server.c++:1873: warning: A DurableObjectNamespace in the config referenced the class "DOQueueHandler", but no such Durable Object class is exported from the worker. Please make sure the class name matches, it is exported, and the class extends 'DurableObject'. Attempts to call to this Durable Object class will fail at runtime, but historically this was not a startup-time error. Future versions of workerd may make this a startup-time error.