LogoMkSaaS文档
网站部署

Cloudflare (使用 D1 数据库)

学习如何将您的项目部署到 Cloudflare Workers 平台，并使用 D1 数据库

本文档将帮助您将 MkSaaS 项目部署到 Cloudflare Workers 平台，并使用 D1 数据库。

重要：使用 cloudflare-d1 分支

部署到 Cloudflare Workers 需要使用 cloudflare-d1 分支而不是 main 分支。此分支包含必要的 OpenNext.js 配置和 针对 Cloudflare 特定平台的适配，并且默认使用 D1 数据库。

如果您希望使用 Postgres 类型数据库，请参考 Cloudflare 部署。

前提条件

在将项目部署到 Cloudflare Workers 之前，请确保您有：

  1. 包含项目代码的 Git 仓库（如 GitHub）
  2. Cloudflare 账户，如果您没有，请在这里注册

关于 Worker 大小限制的说明

Cloudflare Worker 有部署文件的大小限制，在 Workers 免费计划上为 3 MB，在 Workers 付费计划上为 10 MB。构建 Worker 后，wrangler 将显示原始大小和压缩大小：

Total Upload: 13833.20 KiB / gzip: 2295.89 KiB

只有后者（压缩大小）对 Worker 大小限制很重要，所以如果您的项目大于 3 MB，您需要订阅 Workers 付费计划。

部署步骤

切换到 cloudflare-d1 分支

克隆 MkSaaS 模板仓库的 cloudflare-d1 分支，并新建 GitHub 仓库，将代码推送到该仓库：

# Clone the cloudflare-d1 branch of the MkSaaS template repository
git clone -b cloudflare-d1 https://github.com/MkSaaSHQ/mksaas-template.git <your-project-name>
cd <your-project-name>

# Add the upstream repository and fetch the latest changes
git remote add upstream https://github.com/MkSaaSHQ/mksaas-template.git
git fetch upstream

# Remove the origin repository and add your new GitHub repository
git remote remove origin
git remote add origin <your-repository-url>

# Rename the branch to main and push the changes to the origin repository
git branch -M main
git push -u origin main

安装依赖项

安装所有必需的依赖项，包括 Cloudflare Workers 部署所需的 Wrangler CLI 工具：

pnpm install

安装 Wrangler CLI

安装 Wrangler CLI，然后运行 wrangler login 登录到您的 Cloudflare 账户。

pnpm install -g wrangler

# 登录到您的 Cloudflare 账户
wrangler login

设置 Wrangler 配置名称

在 wrangler.jsonc 文件中设置 name 为您的项目名称：

wrangler.jsonc
{
  "name": "your-project-name"
}

创建 D1 数据库

  1. 进入到 Cloudflare 仪表盘
  2. 导航到 Storage & Databases → D1 Databases
  3. 点击 Create database
  4. 输入数据库名称（例如：mksaas-demo）
  5. 选择数据库位置（建议选择离您用户最近的区域）
  6. 点击 Create 创建数据库

创建完成后，记下数据库的 Database ID，后续配置需要用到。

配置 D1 数据库绑定

在 wrangler.jsonc 文件中添加 D1 数据库配置：

wrangler.jsonc
{
  "name": "your-project-name",
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "YOUR_DATABASE_NAME_HERE",
      "database_id": "YOUR_DATABASE_ID_HERE"
    }
  ]
}

将 database_name 替换为您创建的数据库名称，将 database_id 替换为新建的数据库 ID。

配置环境变量

为开发和生产环境设置环境变量：

  1. 对于开发：复制示例文件并配置它们

    cp env.example .env
cp dev.vars.example .dev.vars

  2. 配置变量：按照环境配置文档在 .env 文件中设置所有必需的环境变量，并保持 .dev.vars 不变。

使用 D1 数据库时，您需要注意以下环境变量配置：

  • NEXT_PUBLIC_BASE_URL：您应用程序的基础 URL，对于本地开发，将其设置为 http://localhost:8787 而不是 http://localhost:3000，因为网站将由 opennext-cloudflare 运行，默认情况下会自动在端口 8787 上运行。
  • DATABASE_URL：使用 D1 数据库时，请将 DATABASE_URL 设置为空字符串 DATABASE_URL=""
  • CLOUDFLARE_ACCOUNT_ID：您的 Cloudflare 账户 ID，可以在 Cloudflare 仪表盘的 Account Home 中，点击账号名右侧，选择 Copy account id 获取
  • CLOUDFLARE_DATABASE_ID：您创建的 D1 数据库的 ID，可以在 Cloudflare 仪表盘的 Storage & Databases → D1 Databases → 复制数据库名称右侧的 ID
  • CLOUDFLARE_API_TOKEN：用于数据库操作的 API 令牌，需要在 Manage account → Account API tokens 中创建新的 API 令牌，并授予 D1 数据库编辑权限和其他权限 (如图所示)

API Tokens

D1 数据库配置示例：

# For PostgreSQL(Supabase/Neon): Set DATABASE_URL and leave other D1 configuration empty
DATABASE_URL=""

# For Cloudflare D1: Leave DATABASE_URL empty and configure D1 bindings in wrangler.jsonc
CLOUDFLARE_ACCOUNT_ID="your_account_id_here"
CLOUDFLARE_DATABASE_ID="your_database_id_here"
CLOUDFLARE_API_TOKEN="your_api_token_here"

初始化数据库

数据库创建完成后，需要运行数据库迁移来初始化数据库结构：

pnpm db:generate
pnpm db:migrate

此命令将根据您的 Drizzle ORM 模式创建所有必要的表和结构。

建议通过修改 drizzle.config.ts 文件中的配置，完成对开发数据库和生产数据库的数据库迁移操作。

例如，取消注释 drizzle.config.ts 文件中的 const isProduction = true; 行，完成对生产数据库的数据库迁移操作。

生成类型

配置 .env 和 wrangler.jsonc 文件后，生成 Cloudflare 特定的类型：

pnpm run cf-typegen

此命令将自动生成包含 Cloudflare Worker 运行时环境类型定义的 cloudflare-env.d.ts 文件。

创建 Cloudflare Worker 项目

  1. 进入到 Cloudflare 仪表盘
  2. 导航到 Compute & AI → Workers and Pages → Create → Import a repository
  3. 选择仓库 (默认使用 main 分支)
  4. 配置构建设置：
    • 名称：保持与 wrangler.jsonc 文件中的 name 相同
    • 构建命令：留空
    • 部署命令：pnpm run deploy
    • 根目录：保持默认
    • 构建环境变量：添加 NEXT_PUBLIC_BASE_URL 变量，并设置为 https://<your-project-name>.<account>.workers.dev 或自定义域名

配置环境变量

有两种方式在 Cloudflare 中配置环境变量：

  1. 在 Cloudflare Worker 项目的后台设置中，配置环境变量

    • 进入 Settings → Variables and Secrets
    • 点击 + Add，并添加所有环境变量
    • 点击 Deploy 保存变量并触发构建和部署

  2. 使用 Wrangler CLI 配置环境变量

创建一个 .env.production 文件，并复制 .env 文件中的所有变量，并更新部分环境变量为线上环境变量的值，然后使用 Wrangler CLI 将所有变量配置批量到 Cloudflare Worker 中：

# 创建一个 .env.production 文件，并复制 .env 文件中的所有变量
cp .env .env.production

# 更新 .env.production 文件中的环境变量
# 例如，您需要更新 NEXT_PUBLIC_BASE_URL 环境变量
# 注意：使用 D1 数据库时，DATABASE_URL 应保持为空字符串

# 使用 Wrangler CLI 设置环境变量
# https://developers.cloudflare.com/workers/wrangler/commands/#secret-bulk
# 将 .env.production 文件中的所有变量设置为 Cloudflare Worker 的构建环境变量
wrangler secret bulk .env.production

如果部署之后，线上运行有问题，例如注册或者登录失败，可以观察下 Cloudflare 上构建日志，检查是否提示有环境变量缺失。

如果有提示环境变量缺失，可以在设置中检查 Worker 运行时和构建时配置的环境变量，补充缺失的环境变量，然后重新触发构建。

部署网站

您可以通过两种方式部署应用程序：

选项 1：自动部署

  • 将更改推送到 main 分支 (默认使用 main 分支)
  • Cloudflare 将自动触发构建和部署

选项 2：手动部署

  • 直接从本地机器部署：

    pnpm run deploy

设置自定义域名

成功部署后，网站将在自动生成的域名上可用。您可以：

  • 设置自定义域名，Cloudflare 将自动为您创建 DNS 记录
  • 在 Cloudflare 仪表盘中监控网站，如流量和日志

Cloudflare Worker Settings

最佳实践

  1. 使用 pnpm run dev 进行本地开发

    对于本地开发，优先使用 pnpm run dev 命令，因为它允许更快的开发和调试您的 Next.js 应用程序。在此模式下，代码更改通过热重载快速反映代码修改效果。如果您使用 pnpm run preview，项目将首先构建并在生产模式下运行，这意味着代码更改需要再次运行 pnpm run preview 才能生效。

    如果网站在本地使用 pnpm run dev 正常工作，但在生产中表现异常，请检查生产日志以分析问题。如果生产日志难以访问，您可以在本地运行 pnpm run preview 在类似生产的环境中调试问题。

    请查看 OpenNext.js Cloudflare | 开发和部署 了解更多详细信息。

  2. 为本地开发和生产使用不同的 D1 数据库

    您应该为本地开发和生产使用不同的 D1 数据库。Wrangler 会自动在本地创建 D1 数据库用于开发，生产环境使用您在 Cloudflare 仪表盘中创建的 D1 数据库。这样可以确保开发和生产数据分离，避免数据混淆。

    请查看 Cloudflare D1 文档了解更多详细信息。

  3. 启用 Worker 日志进行调试

    默认情况下，MkSaaS 模板已在 wrangler.jsonc 中启用了可观察性。您可以在项目设置的可观察性部分启用 Worker 日志。这可能需要创建一个新的 R2 存储桶来保存日志数据，需按照仪表盘上的引导进行操作。成功启用后，您可以在日志选项卡中查看应用程序的运行时日志。

    请查看 Cloudflare Wrangler 配置了解更多详细信息。

常见问题

  1. 构建大小过大：如果您的 Worker 超过大小限制，请考虑：

    • 升级到 Workers 付费计划
    • 优化您的包大小
    • 移除不必要的依赖项

  2. 数据库连接问题：确保您的 D1 数据库绑定配置正确，并且数据库 ID 和绑定名称与 wrangler.jsonc 中的配置一致。如果遇到连接问题，检查 Worker 日志以获取详细错误信息。

  3. 环境变量问题：确保所有环境变量都在 Cloudflare 的 Worker 运行时环境中配置。

  4. 类型错误：在任何配置更改后运行 pnpm run cf-types 以重新生成类型定义。

参考资料

视频教程

下一步

现在您了解了如何将网站部署到 Cloudflare Workers，请探索其他相关主题：

Vercel 部署

将网站部署到 Vercel

Docker 部署

使用 Docker 部署网站

Cloudflare 部署

将网站部署到 Cloudflare

数据库

配置数据库

Cloudflare (使用 PG 数据库)

学习如何将您的项目部署到 Cloudflare Workers 平台

数据库

了解数据库选项以及如何为项目配置数据库

目录

前提条件
部署步骤
切换到 cloudflare-d1 分支
安装依赖项
安装 Wrangler CLI
设置 Wrangler 配置名称
创建 D1 数据库
配置 D1 数据库绑定
配置环境变量
初始化数据库
生成类型
创建 Cloudflare Worker 项目
配置环境变量
部署网站
设置自定义域名
最佳实践
常见问题
参考资料
视频教程
下一步