将 TanStack Start 部署到 Cloudflare Workers

TanStack Start 应用可以部署到任何支持 Node.js 或 WinterCG 兼容运行时的平台。本模板专为 Cloudflare Workers 构建，充分利用了 D1、R2 和 Workers AI 的原生绑定。

前提条件

部署之前，你需要准备：

一个 Cloudflare 账号
已为你的账号配置了 D1 数据库
已为资源存储创建了 R2 存储桶
已安装所有项目依赖（pnpm install）——项目脚本内部集成了 Wrangler，无需额外安装

本地开发

在部署之前，先在本地运行开发服务器：

pnpm dev

这将启动 Vite 开发服务器，Miniflare 会模拟 Workers 运行时环境。D1 和 R2 在本地使用磁盘存储进行模拟。

在 .env 中设置你的环境变量（从 .env.example 复制）。.env 是所有配置值的唯一本地来源——不要使用 .env.local 或 .dev.vars 作为主要配置。

数据库配置

模板使用 Drizzle ORM 搭配 Cloudflare D1。生成并应用迁移：

pnpm db:generate
pnpm db:migrate:local

迁移脚本会创建用户、会话、新闻通讯订阅、联系消息和支付记录等相关数据表。

部署到远程时，将迁移应用到你的生产 D1 数据库：

pnpm db:migrate:remote

R2 存储

用户上传的资源（如个人头像）存储在 R2 中。存储桶通过 wrangler.jsonc 中定义的绑定进行访问。无需 API 密钥——R2 使用 Worker 的身份进行身份验证。

配置 R2 的步骤：

在 Cloudflare Dashboard 中创建一个存储桶
将绑定添加到 wrangler.jsonc：

{
  "r2_buckets": [
    {
      "binding": "ASSETS_R2",
      "bucket_name": "your-bucket-name"
    }
  ]
}

运行 pnpm deploy:production 配置绑定

Workers AI

模板内置了 AI 工具，用于摘要、翻译和内容生成，底层使用 Cloudflare Workers AI。本地开发通过 REST API 使用你的 Cloudflare 凭证，生产环境则使用原生的 AI 绑定。

模型在 wrangler.jsonc 中配置，通过 src/server/ai/ 进行访问。无需单独的 API 密钥。

环境变量

项目使用 .env 作为所有配置的唯一来源。运行环境同步工具将配置值推送到 Cloudflare：

# 预览将要同步的内容（不实际执行）
pnpm cloudflare:sync-env --dry-run

# 同步非敏感值到 wrangler.jsonc，并通过 wrangler secret put 上传密钥
pnpm cloudflare:sync-env

该脚本仅将非敏感值（如 PAYMENT_PROVIDER 或 BETTER_AUTH_URL）写入 wrangler.jsonc 的 vars 中。API 密钥等敏感信息直接通过 wrangler secret put 上传——它们绝不会出现在 wrangler.jsonc 或任何提交到仓库的文件中。

切勿手动将密钥编辑到 wrangler.jsonc 中。始终使用 cloudflare:sync-env 保持从 .env 同步的一致性。

部署

项目提供了结构化的部署流程。首先验证你的配置：

# 检查 .env 与已追踪的配置是否同步（如果不同步则拒绝继续）
pnpm deploy:check

# 部署到生产环境
pnpm deploy:production

deploy:check 会验证 .env 是否与已追踪的配置一致。deploy:production 会构建并部署 Worker 包。请始终使用这些脚本，而不是直接调用 Wrangler——它们可确保密钥、环境变量和绑定的一致性。

部署后检查

首次部署后：

验证你的自定义域名路由是否正确
运行 pnpm db:migrate:remote 应用所有待处理的迁移
测试身份认证、支付和邮件流程
在 Cloudflare Dashboard 中设置监控

你的 SaaS 现已上线并运行在 Cloudflare Workers 上，使用 D1 存储数据、R2 管理资源、Workers AI 提供智能能力——一切都在边缘节点上运行。

将 TanStack Start 部署到 Cloudflare Workers

Kiro Finch