132 lines
4.8 KiB
Markdown
132 lines
4.8 KiB
Markdown
# 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)
|