Cloudflare Workers 部署

前置条件

拥有 Cloudflare 账号
依赖已安装（wrangler 与 @cloudflare/vite-plugin 已在 devDependencies）

步骤 1：登录 Cloudflare

cd apps/tanstack-app
npx wrangler login

执行后会自动打开浏览器授权。完成后终端会显示 Successfully logged in。

步骤 2：配置 Hyperdrive（数据库）

先使用你的 PostgreSQL 连接串创建 Hyperdrive（这是线上 Workers 使用的代理配置）：

npx wrangler hyperdrive create tinyship-db \
  --connection-string="postgresql://user:password@host:5432/dbname"

创建完成后会返回一个 Hyperdrive ID。然后在 wrangler.jsonc 中同时配置：

id：线上部署时使用（wrangler deploy 后在 Cloudflare 边缘通过 Hyperdrive 访问数据库）
localConnectionString：本地开发时使用（wrangler dev / pnpm dev:cf 直接连你本机或内网数据库）

示例（与当前项目结构一致）：

"hyperdrive": [
  {
    "binding": "HYPERDRIVE",
    "id": "<your-hyperdrive-id>",
    "localConnectionString": "postgresql://viking:unused@localhost:5432/shipeasy_dev"
  }
]

说明：

本地调试优先走 localConnectionString，便于连接本机数据库并避免依赖线上网络。
部署到 Cloudflare 后不会使用 localConnectionString，而是使用 id 对应的 Hyperdrive 配置。
若你不填 localConnectionString，本地 CF 调试会走 Hyperdrive 的远端连接路径，调试体验通常更慢且更依赖外网。

步骤 3：配置 Secrets

Cloudflare Workers 的敏感配置使用 Secrets（不是 .env 文件）：

# 必填
npx wrangler secret put BETTER_AUTH_SECRET
npx wrangler secret put DATABASE_URL

# 按照需要多次放入 serect

# 2) 也可以使用文件进行一次导入
npx wrangler secret bulk .secrets.json

建议：.secrets.json 仅用于本地临时导入，不要提交到 Git。

非敏感变量建议放在 wrangler.jsonc 的 vars 中（取消注释后填写）：

"vars": {
  "APP_BASE_URL": "https://your-domain.com",
  "BETTER_AUTH_URL": "https://your-domain.com"
}

步骤 4：本地预览

先在本地 Workers 模拟环境中验证：

cd apps/tanstack-app
pnpm dev:cf

该命令会以 CF_DEPLOY=1 运行 Vite + Cloudflare 插件，从而模拟 Workers 运行时。建议验证：

页面在输出 URL（通常 http://localhost:7001）可正常打开
登录 / 注册功能可用
依赖数据库的功能可正常加载
API 端点返回符合预期

步骤 5：部署上线

cd apps/tanstack-app
pnpm run deploy:cf

该命令执行 CF_DEPLOY=1 vite build && wrangler deploy。成功后会输出类似地址：

https://tinyship-tanstack.<your-subdomain>.workers.dev

步骤 6：部署后验证

在部署地址上验证以下端点：

检查项	URL	期望
健康检查	`/api/health`	200 OK
首页	`/en`	页面正常渲染
登录页	`/en/signin`	登录页可访问
数据库功能	`/api/credits/balance`（需会话）	正常返回余额

# 快速烟雾测试
curl -s -o /dev/null -w "%{http_code}" https://your-worker-url/api/health

CF 模式工作原理（开发者说明）

Cloudflare 集成采用**按需启用（opt-in）**方案，不影响常规开发：

┌─────────────────────────────────────────────────┐
│  pnpm dev          (常规开发)                   │
│  → Vite dev server, Node.js, DATABASE_URL       │
│  → 不设置 CF_DEPLOY                             │
│  → 不加载 cloudflare() 插件                     │
├─────────────────────────────────────────────────┤
│  pnpm dev:cf       (CF 本地预览)                │
│  → CF_DEPLOY=1 → 加载 cloudflare() 插件         │
│  → Vite + Cloudflare 插件模拟 Workers 运行时     │
│  → 使用 Hyperdrive 或 DATABASE_URL              │
├─────────────────────────────────────────────────┤
│  pnpm run deploy:cf (生产部署)                  │
│  → CF_DEPLOY=1 → 加载 cloudflare() 插件         │
│  → vite build → 产出 Workers 兼容构建           │
│  → wrangler deploy → 发布到边缘网络             │
└─────────────────────────────────────────────────┘

关键机制：vite.config.ts 会检查 process.env.CF_DEPLOY，仅在该变量存在时才动态导入 @cloudflare/vite-plugin。这意味着：

pnpm dev / pnpm build：纯 Vite/Node.js 流程，无 CF 额外开销
pnpm dev:cf / pnpm run deploy:cf：走 Workers 兼容构建流程

与其他部署方式对比

特性	Cloudflare Workers	Docker	Vercel	传统部署
适用框架	TanStack Start	全部	Next.js	全部
冷启动	< 5ms	无（常驻）	~250ms	无
全球分发	自动	手动	自动	手动
免费额度	10 万次/天	无	有限	无
数据库支持	需 Hyperdrive	原生 TCP	原生 TCP	原生 TCP
上传限制	100MB / 500MB	无限制	50MB	无限制
运维成本	很低	中等	低	高

Cloudflare Workers 适合追求高性能、全球覆盖、低运维的场景。如果你对数据库连接方式或执行时限有顾虑，可优先考虑 Docker 或传统部署。

前置条件

拥有 Cloudflare 账号
依赖已安装（wrangler 与 @cloudflare/vite-plugin 已在 devDependencies）

步骤 1：登录 Cloudflare

cd apps/tanstack-app
npx wrangler login

执行后会自动打开浏览器授权。完成后终端会显示 Successfully logged in。

步骤 2：配置 Hyperdrive（数据库）

先使用你的 PostgreSQL 连接串创建 Hyperdrive（这是线上 Workers 使用的代理配置）：

npx wrangler hyperdrive create tinyship-db \
  --connection-string="postgresql://user:password@host:5432/dbname"

创建完成后会返回一个 Hyperdrive ID。然后在 wrangler.jsonc 中同时配置：

id：线上部署时使用（wrangler deploy 后在 Cloudflare 边缘通过 Hyperdrive 访问数据库）
localConnectionString：本地开发时使用（wrangler dev / pnpm dev:cf 直接连你本机或内网数据库）

示例（与当前项目结构一致）：

"hyperdrive": [
  {
    "binding": "HYPERDRIVE",
    "id": "<your-hyperdrive-id>",
    "localConnectionString": "postgresql://viking:unused@localhost:5432/shipeasy_dev"
  }
]

说明：

本地调试优先走 localConnectionString，便于连接本机数据库并避免依赖线上网络。
部署到 Cloudflare 后不会使用 localConnectionString，而是使用 id 对应的 Hyperdrive 配置。
若你不填 localConnectionString，本地 CF 调试会走 Hyperdrive 的远端连接路径，调试体验通常更慢且更依赖外网。

步骤 3：配置 Secrets

Cloudflare Workers 的敏感配置使用 Secrets（不是 .env 文件）：

# 必填
npx wrangler secret put BETTER_AUTH_SECRET
npx wrangler secret put DATABASE_URL

# 按照需要多次放入 serect

# 2) 也可以使用文件进行一次导入
npx wrangler secret bulk .secrets.json

建议：.secrets.json 仅用于本地临时导入，不要提交到 Git。

非敏感变量建议放在 wrangler.jsonc 的 vars 中（取消注释后填写）：

"vars": {
  "APP_BASE_URL": "https://your-domain.com",
  "BETTER_AUTH_URL": "https://your-domain.com"
}

步骤 4：本地预览

先在本地 Workers 模拟环境中验证：

cd apps/tanstack-app
pnpm dev:cf

该命令会以 CF_DEPLOY=1 运行 Vite + Cloudflare 插件，从而模拟 Workers 运行时。建议验证：

页面在输出 URL（通常 http://localhost:7001）可正常打开
登录 / 注册功能可用
依赖数据库的功能可正常加载
API 端点返回符合预期

步骤 5：部署上线

cd apps/tanstack-app
pnpm run deploy:cf

该命令执行 CF_DEPLOY=1 vite build && wrangler deploy。成功后会输出类似地址：

https://tinyship-tanstack.<your-subdomain>.workers.dev

步骤 6：部署后验证

在部署地址上验证以下端点：

检查项	URL	期望
健康检查	`/api/health`	200 OK
首页	`/en`	页面正常渲染
登录页	`/en/signin`	登录页可访问
数据库功能	`/api/credits/balance`（需会话）	正常返回余额

# 快速烟雾测试
curl -s -o /dev/null -w "%{http_code}" https://your-worker-url/api/health

CF 模式工作原理（开发者说明）

Cloudflare 集成采用**按需启用（opt-in）**方案，不影响常规开发：

┌─────────────────────────────────────────────────┐
│  pnpm dev          (常规开发)                   │
│  → Vite dev server, Node.js, DATABASE_URL       │
│  → 不设置 CF_DEPLOY                             │
│  → 不加载 cloudflare() 插件                     │
├─────────────────────────────────────────────────┤
│  pnpm dev:cf       (CF 本地预览)                │
│  → CF_DEPLOY=1 → 加载 cloudflare() 插件         │
│  → Vite + Cloudflare 插件模拟 Workers 运行时     │
│  → 使用 Hyperdrive 或 DATABASE_URL              │
├─────────────────────────────────────────────────┤
│  pnpm run deploy:cf (生产部署)                  │
│  → CF_DEPLOY=1 → 加载 cloudflare() 插件         │
│  → vite build → 产出 Workers 兼容构建           │
│  → wrangler deploy → 发布到边缘网络             │
└─────────────────────────────────────────────────┘

关键机制：vite.config.ts 会检查 process.env.CF_DEPLOY，仅在该变量存在时才动态导入 @cloudflare/vite-plugin。这意味着：

pnpm dev / pnpm build：纯 Vite/Node.js 流程，无 CF 额外开销
pnpm dev:cf / pnpm run deploy:cf：走 Workers 兼容构建流程

与其他部署方式对比

特性	Cloudflare Workers	Docker	Vercel	传统部署
适用框架	TanStack Start	全部	Next.js	全部
冷启动	< 5ms	无（常驻）	~250ms	无
全球分发	自动	手动	自动	手动
免费额度	10 万次/天	无	有限	无
数据库支持	需 Hyperdrive	原生 TCP	原生 TCP	原生 TCP
上传限制	100MB / 500MB	无限制	50MB	无限制
运维成本	很低	中等	低	高

Cloudflare Workers 适合追求高性能、全球覆盖、低运维的场景。如果你对数据库连接方式或执行时限有顾虑，可优先考虑 Docker 或传统部署。

Cloudflare Workers 部署

前置条件

步骤 1：登录 Cloudflare

步骤 2：配置 Hyperdrive（数据库）

步骤 3：配置 Secrets

步骤 4：本地预览

步骤 5：部署上线

步骤 6：部署后验证

CF 模式工作原理（开发者说明）

与其他部署方式对比

On this page

Cloudflare Workers 部署

前置条件

步骤 1：登录 Cloudflare

步骤 2：配置 Hyperdrive（数据库）

步骤 3：配置 Secrets

步骤 4：本地预览

步骤 5：部署上线

步骤 6：部署后验证

CF 模式工作原理（开发者说明）

与其他部署方式对比

On this page