Cloudflare Workers 部署
基于 TanStack Start 和 Cloudflare Vite 插件的可选部署路径，说明适用场景、构建命令、环境变量和兼容性验证。
Cloudflare Workers 部署适合明确需要 Cloudflare 边缘运行时的项目。01MVP Start 使用 TanStack Start 的 server entry，并通过 Cloudflare Vite 插件生成 Workers 可运行产物。
直接部署到 Cloudflare Workers 需要单独验证数据库连接、文档资产、搜索、Node.js 兼容性和第三方 SDK。不要把它当成默认上线路径。
适用场景
| 场景 | 建议 |
|---|---|
| 只是想快速上线 TanStack Start 产品 | 用 Zeabur 部署 |
| 已经有容器平台或需要自管运行时 | 用 Docker 部署 |
| 明确需要 Cloudflare Workers、边缘网络或 Cloudflare 生态绑定 | 评估本页路径 |
| 只需要 Cloudflare DNS、CDN、WAF | 不需要迁移应用运行时，继续用 Zeabur 或 Docker |
当前脚本
products/01mvp/apps/web/package.json 中保留了 Cloudflare 相关脚本：
vpr @01mvp/web#build:cf
vpr @01mvp/web#preview:cf
vpr @01mvp/web#deploy:cf这些脚本会启用 CF_DEPLOY=1，让 Vite 加载 @cloudflare/vite-plugin，并输出 TanStack Start 的 Workers 产物。脚本不写死生产域名；VITE_WEB_URL 和 VITE_SERVER_URL 优先从外部环境变量、products/01mvp/packages/config/.env 或共享兜底 packages/config/.env 读取。只有这些位置都没有提供时，脚本才使用模板内置的生产 URL 默认值。
Wrangler 配置
配置文件位于 products/01mvp/apps/web/wrangler.jsonc。核心结构如下：
{
"name": "01mvp-start",
"main": "@tanstack/react-start/server-entry",
"compatibility_flags": ["nodejs_compat", "nodejs_compat_populate_process_env"],
"assets": {
"directory": "./dist/client",
"binding": "ASSETS"
}
}正式接入前需要按项目补充：
- 生产域名 routes 或 custom domain
- 数据库连接方式
- Secret 环境变量
- R2、KV、Hyperdrive 等 Cloudflare 绑定
- 日志与观测配置
本地预览
安装依赖
vp install --frozen-lockfile生成 Worker 构建产物
vpr @01mvp/web#build:cf本地预览
vpr @01mvp/web#preview:cf打开预览地址，检查首页、文档页、登录入口、API 路由和静态资源。
环境变量和 Secret
Cloudflare Workers 不会自动读取 Zeabur 或本地 .env.prd 环境变量。生产密钥要用 Wrangler Secret 或 Cloudflare Dashboard 配置。
cd products/01mvp/apps/web
vp exec wrangler secret put DATABASE_URL
vp exec wrangler secret put BETTER_AUTH_SECRET
vp exec wrangler secret put OPENAI_API_KEY构建期需要 VITE_WEB_URL 和 VITE_SERVER_URL 指向目标域名。可以把它们写入部署环境变量；本地验证时也可以临时在命令前传入：
VITE_WEB_URL=https://your-domain.com \
VITE_SERVER_URL=https://your-domain.com/api \
vpr @01mvp/web#build:cf公开变量可以放在 wrangler.jsonc 的 vars 中，但不要把真实密钥写进 vars。
Serverless/edge 数据库连接需要单独评估。直连 PostgreSQL 可能受连接数、网络和 TLS 影响，生产环境通常需要连接池、Hyperdrive 或数据库提供商的 Serverless 连接方案。
兼容性验证
Cloudflare Workers 和 Node.js 运行时不完全一致。部署前至少验证：
-
vpr @01mvp/web#build:cf成功 -
vpr @01mvp/web#preview:cf能打开首页和核心文档页 -
/api/docs-search能返回搜索结果 - 登录、注册、OAuth 回调和 session 行为正常
- Drizzle 能连接目标数据库
- 文件上传、S3/R2 访问和公开 URL 正常
- AI、邮件、支付 SDK 在 Workers 运行时无兼容性错误
- 静态资源和文档 assets 无 404
发布
确认本地预览通过后再执行部署：
vpr @01mvp/web#deploy:cf部署后检查：
vp exec wrangler deployments status再访问生产域名，按部署后验证逐项检查。
常见问题
上线检查
-
wrangler.jsonc中的 worker 名称、域名和 bindings 已按项目更新 - 所有密钥已通过 Wrangler Secret 或 Dashboard 配置
- 数据库连接方案已验证
-
build:cf和preview:cf都通过 - 文档 assets、搜索、登录、上传、AI、邮件和支付都在 Workers 预览环境验证过
- 部署后确认 Cloudflare 已收到最新版本
这篇文档有问题？