签入版本
This commit is contained in:
小蚂蚁云
@@ -1,131 +1,73 @@
|
||||
# 11.5 前端部署
|
||||
|
||||
:::tip 概述
|
||||
本节说明前端项目的构建与部署流程，包括构建命令、Nginx 配置、Gzip 压缩和部署步骤。适用于将前端静态资源部署到 Nginx 服务器。
|
||||
前端构建为纯静态产物（dist/），由 Nginx 直接服务。部署三要素：构建时环境变量、history 模式回退、与后端的路径对齐。
|
||||
:::
|
||||
|
||||
## 前置要求
|
||||
|
||||
| 依赖 | 版本要求 | 说明 |
|
||||
|------|----------|------|
|
||||
| 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
|
||||
pnpm install --frozen-lockfile
|
||||
pnpm build # 产物输出 dist/
|
||||
```
|
||||
|
||||
构建产物在 `ui/dist/` 目录。
|
||||
构建前确认 `.env.production`：
|
||||
|
||||
### 环境变量配置
|
||||
| 键 | 生产值 |
|
||||
|---|---|
|
||||
| VITE_GLOB_API_URL | 留空（同源反代）或网关基址 |
|
||||
| VITE_GLOB_API_URL_PREFIX | /api |
|
||||
| VITE_BUILD_COMPRESS | gzip（或 none，交 Nginx 压缩） |
|
||||
|
||||
构建前可修改环境变量：
|
||||
|
||||
```bash
|
||||
# .env.production — 生产环境构建配置
|
||||
VITE_GLOB_API_URL=/api # API 基础路径（Nginx 代理到后端）
|
||||
VITE_GLOB_API_URL_PREFIX= # API 路径前缀（一般留空）
|
||||
```
|
||||
|
||||
## Nginx 配置
|
||||
## Nginx 站点配置要点
|
||||
|
||||
```nginx
|
||||
# =============================================================================
|
||||
# Nginx 站点配置 — Vue3 前端 SPA
|
||||
# =============================================================================
|
||||
# 用途：托管前端静态资源，API 请求反向代理到后端
|
||||
# 配置路径：/etc/nginx/sites-available/rxthinkcmf-admin
|
||||
# =============================================================================
|
||||
|
||||
server {
|
||||
# 监听 80 端口（生产环境建议改为 443 + SSL）
|
||||
listen 80;
|
||||
# 绑定域名（替换为实际域名）
|
||||
server_name admin.example.com;
|
||||
listen 443 ssl;
|
||||
server_name your-domain;
|
||||
|
||||
# 前端构建产物目录（pnpm build 输出）
|
||||
root /www/admin/dist;
|
||||
root /var/www/easygoadmin;
|
||||
index index.html;
|
||||
|
||||
# -----------------------------------------------------------------
|
||||
# Vue Router History 模式
|
||||
# -----------------------------------------------------------------
|
||||
# SPA 路由在浏览器端处理，Nginx 需要将所有非文件请求回退到 index.html
|
||||
# 例：访问 /user/list → 实际由 Vue Router 在浏览器端渲染
|
||||
# try_files 依次尝试：$uri（真实文件）→ $uri/（目录）→ /index.html（回退）
|
||||
# history 模式回退（刷新子路由 404 的根治）
|
||||
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 反代到应用
|
||||
location /api/ {
|
||||
proxy_pass http://127.0.0.1:8000;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
}
|
||||
|
||||
# -----------------------------------------------------------------
|
||||
# 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
|
||||
# 静态资源长缓存（带 hash 的 assets）
|
||||
location /assets/ {
|
||||
expires 30d;
|
||||
add_header Cache-Control "public, immutable";
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 部署步骤
|
||||
## 发布流程
|
||||
|
||||
```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
|
||||
```text
|
||||
① pnpm build → 上传 dist/ 到站点根（原子切换：软链切换目录）
|
||||
② 刷新浏览器验证（强刷清旧资源缓存）
|
||||
③ 回滚 = 软链切回上一版目录
|
||||
```
|
||||
|
||||
## 常见问题
|
||||
|
||||
| 问题 | 原因 | 解决方案 |
|
||||
|------|------|----------|
|
||||
| 刷新 404 | Nginx 未配置 try_files | 添加 `try_files $uri $uri/ /index.html` |
|
||||
| API 404 | 代理配置错误 | 检查 `proxy_pass` 地址 |
|
||||
| 静态资源 404 | 路径错误 | 检查 `root` 路径是否正确 |
|
||||
| 白屏 | 构建失败或路径错误 | 检查构建日志和 Nginx 错误日志 |
|
||||
| 样式错乱 | 字体文件加载失败 | 检查字体文件路径和 CORS 配置 |
|
||||
| 现象 | 原因 |
|
||||
|---|---|
|
||||
| 刷新 404 | history 回退缺失（try_files /index.html） |
|
||||
| 接口 404/跨域 | 反代路径不对 / VITE_GLOB_API_URL 与部署形态不匹配 |
|
||||
| 白屏（懒加载失败） | 菜单 component 路径与产物文件不符；或 base 路径配置错 |
|
||||
| 旧版本缓存 | index.html 未禁缓存（应 no-cache，assets 长缓存） |
|
||||
|
||||
## 相关文档
|
||||
## 相关
|
||||
|
||||
- [后端部署](/zh/deploy/backend.html)
|
||||
- [Docker 生产部署](/zh/deploy/docker.html)
|
||||
- [环境与构建配置](/zh/frontend/env-config.html)
|
||||
- [9.3 环境与构建配置](/zh/frontend/env-config.html)
|
||||
|
||||
Reference in New Issue
Block a user