# 11.5 前端部署

:::tip 概述
前端构建为纯静态产物（dist/），由 Nginx 直接服务。部署三要素：构建时环境变量、history 模式回退、与后端的路径对齐。
:::

## 构建

```bash
cd ui
pnpm install --frozen-lockfile
pnpm build          # 产物输出 dist/
```

构建前确认 `.env.production`：

| 键 | 生产值 |
|---|---|
| VITE_GLOB_API_URL | 留空（同源反代）或网关基址 |
| VITE_GLOB_API_URL_PREFIX | /api |
| VITE_BUILD_COMPRESS | gzip（或 none，交 Nginx 压缩） |

## Nginx 站点配置要点

```nginx
server {
    listen 443 ssl;
    server_name your-domain;

    root /var/www/easygoadmin;
    index index.html;

    # history 模式回退（刷新子路由 404 的根治）
    location / {
        try_files $uri $uri/ /index.html;
    }

    # API 反代到应用
    location /api/ {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # 静态资源长缓存（带 hash 的 assets）
    location /assets/ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
}
```

## 发布流程

```text
① pnpm build → 上传 dist/ 到站点根（原子切换：软链切换目录）
② 刷新浏览器验证（强刷清旧资源缓存）
③ 回滚 = 软链切回上一版目录
```

## 常见问题

| 现象 | 原因 |
|---|---|
| 刷新 404 | history 回退缺失（try_files /index.html） |
| 接口 404/跨域 | 反代路径不对 / VITE_GLOB_API_URL 与部署形态不匹配 |
| 白屏（懒加载失败） | 菜单 component 路径与产物文件不符；或 base 路径配置错 |
| 旧版本缓存 | index.html 未禁缓存（应 no-cache，assets 长缓存） |

## 相关

- [9.3 环境与构建配置](/zh/frontend/env-config.html)