Cloudflare Workers + Vue 项目部署踩坑与解决方案总结

1. CI/CD 及多环境部署目标

  • 需求：Vue3 + Vite 项目，支持 GitHub Actions 自动部署到 Cloudflare Workers，mock API（json-server 数据）可用，静态资源与 API 一体化。

2. 主要问题与解决办法

2.1 wrangler.toml 配置与 secrets 注入

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

2.2 wrangler 4.x 静态资源绑定

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

2.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。

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

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

2.5 兼容性与调试

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

2.6 Worker 端健壮性

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

3. 最终推荐方案

  • wrangler.toml： 
    1
2

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

    let db = env.DB_JSON;
  • workflow 无需 base64 注入，直接 deploy。

4. 其他注意事项

  • db.json 必须为标准 JSON，内容完整。
  • 静态资源目录与 wrangler.toml 配置一致。
  • 所有 mock API 路径、字段需与前端代码一致。

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