5.4 KiB
5.4 KiB
11.5 前端部署
:::tip 概述 本节说明前端项目的构建与部署流程，包括构建命令、Nginx 配置、Gzip 压缩和部署步骤。适用于将前端静态资源部署到 Nginx 服务器。 :::
前置要求
| 依赖 | 版本要求 | 说明 |
|---|---|---|
| Node.js | >= 14.18（建议 18+，实测 22 LTS） | JavaScript 运行时（ui/ 为 Vite 3） |
| pnpm | >= 9.0 | 包管理工具（ui/pnpm-lock.yaml） |
| Nginx | >= 1.20 | Web 服务器 |
构建
# 进入前端项目目录（注意：前端在 ui/ 子目录）
cd ui
# 安装项目依赖（从 pnpm-lock.yaml 精确安装，确保版本一致）
pnpm install
# 执行生产环境构建（Vite 压缩代码、Tree-shaking、分包 + postBuild 后处理）
pnpm build
构建产物在 ui/dist/ 目录。
环境变量配置
构建前可修改 ui/.env.production：
# ui/.env.production — 生产环境构建配置
VITE_GLOB_API_URL = # API 基础路径（留空表示同源，由 Nginx 代理）
VITE_GLOB_API_URL_PREFIX = /api # 接口前缀（后端路由统一在 /api 下）
VITE_GLOB_UPLOAD_URL = # 图片上传地址（跨域部署时配置后端域名）
VITE_GLOB_IMG_URL = # 图片前缀地址
VITE_DROP_CONSOLE = true # 删除 console 调试语句
VITE_BUILD_COMPRESS = 'none' # 构建压缩：gzip / brotli / none
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/ 开头的请求转发到后端 Laravel 服务
# 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 配置 |
| 登录后接口 401 | 跨域部署时 token 未携带 | 检查 VITE_GLOB_API_URL 与后端 CORS_ALLOW_ORIGIN 是否一致 |