137 lines
5.4 KiB
Markdown
137 lines
5.4 KiB
Markdown
# 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 服务器 |
|
||
|
||
## 构建
|
||
|
||
```bash
|
||
# 进入前端项目目录（注意：前端在 ui/ 子目录）
|
||
cd ui
|
||
|
||
# 安装项目依赖（从 pnpm-lock.yaml 精确安装，确保版本一致）
|
||
pnpm install
|
||
|
||
# 执行生产环境构建（Vite 压缩代码、Tree-shaking、分包 + postBuild 后处理）
|
||
pnpm build
|
||
```
|
||
|
||
构建产物在 `ui/dist/` 目录。
|
||
|
||
### 环境变量配置
|
||
|
||
构建前可修改 `ui/.env.production`：
|
||
|
||
```bash
|
||
# 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
|
||
# =============================================================================
|
||
# 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
|
||
}
|
||
}
|
||
```
|
||
|
||
## 部署步骤
|
||
|
||
```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 配置 |
|
||
| 登录后接口 401 | 跨域部署时 token 未携带 | 检查 `VITE_GLOB_API_URL` 与后端 `CORS_ALLOW_ORIGIN` 是否一致 |
|
||
|
||
## 相关文档
|
||
|
||
- [后端部署](/zh/deploy/backend.html)
|
||
- [Docker 生产部署](/zh/deploy/docker.html)
|
||
- [环境与构建配置](/zh/frontend/env-config.html)
|