Cloudflare Workers + Vue 项目部署全流程踩坑复盘

1. 目标与环境

  • Vue3 + Vite + TypeScript + TailwindCSS
  • mock API（json-server 数据）支持
  • 多平台自动化部署（GitHub Pages、Deno Deploy、Cloudflare Workers）
  • 统一 API base 配置，环境变量区分开发/生产

2. CI/CD 文件与平台

  • .github/workflows/ci-cd.yml：GitHub Pages 自动部署，含 base 路径 patch
  • .github/workflows/deno-deploy.yml：Deno Deploy 自动部署，支持静态+mock API
  • .github/workflows/cloudflare-pages.yml：Cloudflare Pages 部署（后期未用）
  • .github/workflows/cloudflare-workers.yml：Cloudflare Workers 自动部署，mock API 支持

3. 主要问题与解决办法

3.1 wrangler.toml 配置与 secrets 注入

  • 问题：wrangler.toml 里 account_id = "${{ secrets.CF_ACCOUNT_ID }}" 只有 wrangler-action@v4+ 支持，v3 需写死账号ID。
  • 解决：升级 wrangler-action 到 v3，配合 wrangler 4.x，支持 secrets 注入。

3.2 wrangler 4.x 静态资源绑定

  • 问题：assets = "./dist" 报类型错误，需对象格式，且字段应为 directory。
  • 解决：用 [assets]\ndirectory = "./dist"。

3.3 mock 数据 DB_JSON 注入

  • 问题1：直接用 $GITHUB_ENV 注入 base64，内容过长会被截断，导致 atob 报错。
  • 问题2：wrangler.toml 的 [vars] DB_JSON = { file = "./db.json" } 注入后，env.DB_JSON 是对象，不是字符串。
  • 解决：
    • 采用 wrangler.toml 的 file 语法自动注入 db.json，无需 base64，无长度限制。
    • Worker 端直接用 let db = env.DB_JSON;，不再 JSON.parse/atob。

3.4 db.json 文件未被正确注入

  • 问题：build 步骤后 db.json 被覆盖/丢失，或路径不对。
  • 解决：确保 db.json 与 wrangler.toml 同级，且 build 步骤不影响。

3.5 兼容性与调试

  • 问题：不同平台 base64 命令参数不兼容，导致注入内容异常。
  • 解决：用 base64 < db.json | tr -d '\n' 兼容所有平台。
  • 增加 workflow 步骤输出 db.json 内容和 base64，便于排查。

3.6 Worker 端健壮性

  • 问题：mock 数据解析失败时 500，难以定位。
  • 解决：Worker 端加 try/catch，返回详细错误信息。

3.7 入口文件静态资源处理

  • 问题：老写法 import manifest from '__STATIC_CONTENT_MANIFEST' 在 wrangler 4.x 不兼容。
  • 解决：用 assets 配置和 env.ASSETS.fetch(request) 兜底。

3.8 多平台部署兼容

  • 问题：Deno Deploy、GitHub Pages、Cloudflare Workers 各自有 base 路径、mock API、静态资源等兼容细节。
  • 解决：统一 API_BASE_URL 配置，组件全部 import config.ts，CI/CD 自动 patch base。

4. 最终推荐方案

  • wrangler.toml： 
    1
2
3
4

    [vars]
DB_JSON = { file = "./db.json" }
[assets]
directory = "./dist"
  • cloudflare_worker.ts： 
    1

    let db = env.DB_JSON;
  • workflow 无需 base64 注入，直接 deploy。
  • 其他平台见各自 workflow 文件。

5. 其他注意事项

  • db.json 必须为标准 JSON，内容完整。
  • 静态资源目录与 wrangler.toml 配置一致。
  • 所有 mock API 路径、字段需与前端代码一致。
  • 多平台部署时注意 base 路径 patch 和 API 地址切换。

本文件为自动化部署与 mock API 支持全流程复盘，供后续团队参考。