构建部署

Art Design Pro X 最终生成静态文件，可以部署到 Nginx、CDN、对象存储或其他静态托管平台。静态部署只负责前端资源，认证、业务 API、上传和下载仍需要客户后端或网关。

发布前准备

建议在发布分支确认：

• Node.js >= 20.19.0。
• pnpm >= 8.8.0。
• 使用锁文件安装依赖。
• .env.production 已切换到生产配置。
• 生产域名、HTTPS 和 API 网关已经准备完成。
• 需要保留的业务页面已完成后端接入与权限验收。
• 未使用的演示模块、测试账号和供应商入口已按交付要求处理。

生产环境变量

根路径部署示例：

# .env.production
VITE_BASE_URL = /
VITE_API_URL = /
VITE_DROP_CONSOLE = true

推荐让浏览器请求同源 /api，再由生产网关转发到后端。这样可以减少 CORS、Cookie 和多环境域名问题。

如果使用独立 API 域名：

VITE_API_URL = https://api.example.com

后端需要正确配置 CORS、允许的请求头和 HTTPS。

不要把当前演示接口直接作为客户生产接口

交付源码中的 .env.production 可能保留演示或联调地址。正式构建前必须替换为客户环境，并检查构建产物中没有测试 Token、密钥或内部地址。

构建前检查

完整发布检查：

pnpm install --frozen-lockfile
pnpm release:check

pnpm release:check 会依次执行：

pnpm security:check
  -> pnpm lint
  -> pnpm build

其中 pnpm build 会先执行 TypeScript 检查，再生成生产包。

如果只需要单独构建：

pnpm build

构建产物位于：

dist/
├── index.html
├── assets/
├── version.json
└── *.gz

实际文件会根据页面和依赖拆分为多个带 Hash 的 JS、CSS 与资源文件。

本地预览

不要只通过双击 dist/index.html 验证生产包。使用：

pnpm serve

预览时至少检查：

• 登录与退出。
• 页面刷新后的会话恢复。
• 动态菜单和隐藏详情页。
• 异步页面 Chunk 加载。
• API 和上传地址。
• 亮色、暗色和移动端。
• version.json 可访问。

根路径部署

Nginx 示例：

server {
  listen 443 ssl http2;
  server_name admin.example.com;

  root /srv/art-design-pro-x/dist;
  index index.html;

  location / {
    try_files $uri $uri/ /index.html;
  }

  location /api/ {
    proxy_pass http://business-api/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }

  location /uploads/ {
    proxy_pass http://file-service/;
    proxy_set_header Host $host;
  }

  location = /version.json {
    add_header Cache-Control "no-store, no-cache, must-revalidate";
  }

  location ~* \.(js|css|png|jpg|jpeg|webp|svg|ico|woff2?)$ {
    expires 7d;
    add_header Cache-Control "public, max-age=604800, immutable";
  }
}

proxy_pass 是否保留 /api 前缀取决于客户后端路由。上线前应使用实际请求确认，不能只复制示例。

项目使用 Hash 路由，业务地址位于 /#/...，通常不依赖服务端为每条前端路由配置回退。保留 try_files 仍有助于处理入口和静态路径。

子目录部署

部署到：

https://example.com/admin/

配置：

VITE_BASE_URL = /admin/

重新执行 pnpm build，不能在构建后直接把根路径产物移动到子目录。

Nginx 示例：

location /admin/ {
  alias /srv/art-design-pro-x/dist/;
  try_files $uri $uri/ /admin/index.html;
}

location = /admin/version.json {
  alias /srv/art-design-pro-x/dist/version.json;
  add_header Cache-Control "no-store, no-cache, must-revalidate";
}

子目录部署重点验证：

• index.html 中 JS 和 CSS 地址包含正确基础路径。
• 动态导入页面没有 404。
• Logo、字体和图片路径正确。
• version.json 地址正确。
• API 是走根路径 /api，还是也需要子目录前缀。

构建版本检测

构建会生成 version.json，包含版本号、构建标识和更新策略。相关环境变量位于 .env：

VITE_BUILD_ID =
VITE_VERSION_UPDATE_ENABLED = false
VITE_VERSION_FORCE_UPDATE = false
VITE_VERSION_UPDATE_MESSAGE =
VITE_VERSION_CHECK_INTERVAL = 300000
VITE_VERSION_SNOOZE_DURATION = 1800000

推荐由 CI 注入提交 SHA：

VITE_BUILD_ID="$GIT_COMMIT_SHA" pnpm build

version.json 不应被 CDN 或浏览器长期缓存，否则前端无法及时发现新版本。带内容 Hash 的静态资源可以长期缓存。

Gzip 与静态资源

构建会为 10 KB 以上资源生成 .gz 文件，同时保留原文件。Web 服务器需要配置优先使用预压缩文件，否则 .gz 只会占用磁盘而不会生效。

不同平台配置方式不同，请确认响应头：

Content-Encoding: gzip

不要对 version.json 和 index.html 使用长期 immutable 缓存。

部署方式选择

方式	适合场景	注意事项
Nginx	企业内网、同源 API 网关	代理、缓存和 HTTPS 都可集中配置
CDN + 对象存储	公网静态资源、高访问量	index.html 与 version.json 缓存需单独控制
容器	统一发布平台	镜像只需静态服务器和 dist，不要把源码依赖当运行时
平台静态托管	快速部署	确认 Hash 路由、子目录和响应头支持

回滚策略

推荐每次发布保留：

• 完整 dist 产物。
• Git 提交 SHA 与构建 ID。
• 生产环境变量的非敏感快照。
• 对应后端版本和数据库迁移记录。

回滚时应整体切换前端产物，不能只替换部分 JS 文件。带 Hash 的旧资源可短期保留，避免仍打开旧页面的用户请求 404。

发布后验收

1. 使用真实生产账号登录。
2. 刷新受保护页面，确认会话恢复。
3. 验证不同角色的菜单、URL 直达和按钮权限。
4. 验证核心查询、分页、新增、编辑和删除。
5. 验证上传、下载、导出和异步任务。
6. 检查浏览器 Console 和 Network 没有持续错误。
7. 检查动态 Chunk、图片、字体和 version.json。
8. 检查桌面端、移动端、亮色和暗色。
9. 检查未接后端的页面不会伪造写入成功。
10. 检查监控、日志、告警和回滚路径可用。

出现部署问题时，先查阅常见问题中的“构建与部署”。