ADR-009: 从 Cloudflare Pages 迁移到通用 static preset + 多环境构建

Status

Accepted

Date

2026-04-01

Context

项目原部署方案使用 Cloudflare Pages（Nitro preset cloudflare-pages-static），但正式上线需要三套环境（测试、预发布、生产），均部署在公司内部服务器，不再使用 Cloudflare。

需求：

1. 三套环境通过不同的 API 地址区分（NUXT_PUBLIC_API_BASE、NUXT_PUBLIC_WS_BASE）
2. 构建产物为纯静态文件，用 nginx 托管
3. 短期内无 CI/CD（GitHub Actions self-hosted runner 受网络限制），手动构建部署

Options

A. 保持 Cloudflare Pages preset，通过环境变量在运行时切换

• 优点：不改 preset
• 缺点：Cloudflare 专用 preset 在内部服务器部署无意义，且 ssr: false 下运行时环境变量不生效（SPA 在构建时内联）

B. 切换到 static preset + --dotenv 多环境构建（选择此方案）

• 优点：通用、简单，构建产物为纯 HTML/JS/CSS，任何静态服务器可托管
• 缺点：每个环境需要单独构建

C. 切换到 node-server preset

• 优点：支持 server routes、API 代理
• 缺点：ssr: false 下不需要 Node 运行时，增加部署复杂度

Decision

采用方案 B：

1. Nitro preset 改为 static
2. 每个环境维护独立的 .env.{env} 文件（.env.test、.env.staging、.env.production）
3. 构建脚本通过 nuxt generate --dotenv .env.{env} 加载对应环境变量
4. nuxt.config.ts 中 runtimeConfig.public 只声明默认空值，由 Nuxt 自动映射 NUXT_PUBLIC_* 环境变量

注：已在后续重构中扁平化为单仓，Turborepo 相关配置已移除。

Consequences

• 构建命令：pnpm build:test、pnpm build:staging、pnpm build:prod
• 产物路径：.output/public/（项目根目录），直接部署到 nginx
• 环境文件通过 .gitignore 白名单提交到仓库（存储 API 地址，非密钥）
• 未来接入 CI/CD 时，只需在 workflow 中调用对应构建命令即可