VibeAny 部署到 Cloudflare Workers 完全指南

本文详细介绍如何将 VibeAny（基于 TanStack Start + React 19 的全栈 AI 应用模板）部署到 Cloudflare Workers，包括分支切换、环境变量配置、包体积优化等关键步骤。

前置条件

开始部署前，请确保已准备以下内容：

• Wrangler CLI 已安装
• Cloudflare 账号
• 可公开访问的 PostgreSQL 数据库（推荐 Supabase 或 Neon）

安装 Wrangler 并登录：

npm install -g wrangler
wrangler login

部署流程

1. 切换到 Cloudflare 分支

VibeAny 项目使用独立分支 `feat/cloudflare` 来支持 Workers 部署。该分支包含必要的 Vite 插件和配置文件：

git checkout feat/cloudflare
git rebase main

2. 上传环境变量

Workers 不会读取 `.env` 文件，需要手动将环境变量上传到 Cloudflare：

# 从 .env.production 生成 JSON 文件
grep -v '^#' .env.production | grep '=' | sed 's/^\\([^=]*\\)=\\(.*\\)$/"\\1": "\\2"/' | paste -sd',' | sed 's/^/{/' | sed 's/$/}/' > /tmp/secrets.json

# 批量上传
wrangler secret bulk /tmp/secrets.json
rm /tmp/secrets.json

以 `VITE_` 为前缀的环境变量会在构建时内联，不需要作为 secret 上传。

3. 构建并部署

执行部署命令：

pnpm run deploy

该命令会先执行 `vite build`，再执行 `wrangler deploy`。部署成功后输出示例：

Total Upload: ~13500 KiB / gzip: ~2330 KiB
Deployed vibe-any-tanstack triggers
  https://vibe-any-tanstack.<your-account>.workers.dev

自定义域名

1. 进入 Cloudflare Dashboard → Workers & Pages → 你的 Worker → Settings → Domains & Routes
2. 点击 Add → Custom Domain
3. 输入域名（必须在 Cloudflare DNS 上）

feat/cloudflare 分支的改动说明

相比 `main` 分支，该分支只修改了两个文件：

包体积优化策略

Workers 免费版有 3 MiB gzip 的体积限制。`feat/cloudflare` 分支通过 SSR stubs 技术优化包体积：

这些 stubs 仅作用于 SSR bundle，客户端代码仍然正常加载完整库。

常见问题

查看实时日志

wrangler tail --format pretty

查看包体积明细

wrangler deploy --dry-run --outdir .wrangler/dist

"Cannot access 'pg' before initialization"

该错误表示使用了 `pg`（node-postgres）而非 `postgres`（postgres.js）。确保 `feat/cloudflare` 分支已 rebase 到最新的 `main`。

包体积超过 3 MiB

如果新增了重型依赖，需要在 `vite.config.ts` 的 `ssrOnlyStubs()` 插件中添加对应的 stub，或将其改为动态 import。

总结

VibeAny 项目通过 `feat/cloudflare` 分支提供了完整的 Cloudflare Workers 部署支持，主要解决了以下挑战：

1. 包体积限制：通过 SSR stubs 将 gzip 后体积控制在 3 MiB 以内
2. 数据库兼容：使用 `postgres.js` 替代 `pg`，兼容 Workers 运行时
3. 代码高亮：使用 JavaScript 正则引擎替代 WASM，避免兼容性问题
4. 流程简化：一条命令完成构建和部署

按照本文步骤操作，即可将 VibeAny 应用部署到 Cloudflare Workers 边缘节点，享受低延迟和高可用性。

深入阅读

• SSR Stubs 技术详解：优化 Cloudflare Workers 部署的包体积 - 深入了解 SSR stubs 的工作原理和实现细节

• Shiki 代码高亮完全指南 - 了解代码高亮的详细配置和 Workers 适配方案

• Mermaid 图表绘制完全指南 - 图表绘制的详细教程

• Tiptap 富文本编辑器完全指南 - 富文本编辑器的配置和使用