# 11.5 前端部署

:::tip 概述
本节说明前端项目的构建与部署流程，包括构建命令、Nginx 配置、Gzip 压缩和部署步骤。适用于将前端静态资源部署到 Nginx 服务器。
:::

## 前置要求

| 依赖 | 版本要求 | 说明 |
|------|----------|------|
| Node.js | >= 18.0 | JavaScript 运行时 |
| pnpm | >= 8.0 | 包管理工具 |
| Nginx | >= 1.20 | Web 服务器 |

## 构建

```bash
# 进入前端项目目录
cd ui

# 安装项目依赖（从 pnpm-lock.yaml 精确安装，确保版本一致）
pnpm install

# 执行生产环境构建（Vite 会压缩代码、Tree-shaking、分包）
pnpm build
```

构建产物在 `ui/dist/` 目录。

### 环境变量配置

构建前可修改环境变量：

```bash
# .env.production — 生产环境构建配置
VITE_GLOB_API_URL=/api              # API 基础路径（Nginx 代理到后端）
VITE_GLOB_API_URL_PREFIX=           # API 路径前缀（一般留空）
```

## Nginx 配置

```nginx
# =============================================================================
# Nginx 站点配置 — Vue3 前端 SPA
# =============================================================================
# 用途：托管前端静态资源，API 请求反向代理到后端
# 配置路径：/etc/nginx/sites-available/rxthinkcmf-admin
# =============================================================================

server {
    # 监听 80 端口（生产环境建议改为 443 + SSL）
    listen 80;
    # 绑定域名（替换为实际域名）
    server_name admin.example.com;

    # 前端构建产物目录（pnpm build 输出）
    root /www/admin/dist;
    index index.html;

    # -----------------------------------------------------------------
    # Vue Router History 模式
    # -----------------------------------------------------------------
    # SPA 路由在浏览器端处理，Nginx 需要将所有非文件请求回退到 index.html
    # 例：访问 /user/list → 实际由 Vue Router 在浏览器端渲染
    # try_files 依次尝试：$uri（真实文件）→ $uri/（目录）→ /index.html（回退）
    location / {
        try_files $uri $uri/ /index.html;
    }

    # -----------------------------------------------------------------
    # 静态资源缓存
    # -----------------------------------------------------------------
    # Vite 构建的文件名包含 content hash（如 app.a1b2c3.js），
    # 文件内容变化 → 文件名变化 → 浏览器自动请求新文件
    # 因此可以放心设置长期缓存（30 天）
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    # -----------------------------------------------------------------
    # API 反向代理
    # -----------------------------------------------------------------
    # 将 /api/ 开头的请求转发到后端 ThinkPHP 服务
    # proxy_pass 末尾的 / 表示替换匹配的路径前缀
    location /api/ {
        proxy_pass http://127.0.0.1:8000;           # 后端服务地址
        proxy_set_header Host $host;                 # 传递原始 Host 头
        proxy_set_header X-Real-IP $remote_addr;     # 传递客户端真实 IP
    }
}
```

## 部署步骤

```bash
# -----------------------------------------------------------------------------
# 第 1 步：构建前端项目
# -----------------------------------------------------------------------------
cd ui && pnpm install && pnpm build     # 安装依赖并执行生产构建

# -----------------------------------------------------------------------------
# 第 2 步：将构建产物复制到 Nginx 站点目录
# -----------------------------------------------------------------------------
# -r → 递归复制目录
# dist/* → 构建产物（HTML、JS、CSS、图片等）
cp -r dist/* /www/admin/dist/

# -----------------------------------------------------------------------------
# 第 3 步：重载 Nginx 配置（不中断服务）
# -----------------------------------------------------------------------------
# reload → 优雅重载（不断开现有连接）
# 与 restart 的区别：restart 会断开所有连接，reload 不会
nginx -s reload
```

## 常见问题

| 问题 | 原因 | 解决方案 |
|------|------|----------|
| 刷新 404 | Nginx 未配置 try_files | 添加 `try_files $uri $uri/ /index.html` |
| API 404 | 代理配置错误 | 检查 `proxy_pass` 地址 |
| 静态资源 404 | 路径错误 | 检查 `root` 路径是否正确 |
| 白屏 | 构建失败或路径错误 | 检查构建日志和 Nginx 错误日志 |
| 样式错乱 | 字体文件加载失败 | 检查字体文件路径和 CORS 配置 |

## 相关文档

- [后端部署](/zh/deploy/backend.html)
- [Docker 生产部署](/zh/deploy/docker.html)
- [环境与构建配置](/zh/frontend/env-config.html)