11.5 前端部署

概述

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

前置要求

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

构建

# 进入前端项目目录
cd ui

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

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

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

环境变量配置

构建前可修改环境变量：

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

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
    }
}

部署步骤

# -----------------------------------------------------------------------------
# 第 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 配置

相关文档

• 后端部署
• Docker 生产部署
• 环境与构建配置