298 lines
6.8 KiB
Markdown
298 lines
6.8 KiB
Markdown
# H5 版本部署文档
|
||
|
||
本文档介绍如何将项目编译成 H5 版本并部署到服务器，通过 Nginx 运行和代理访问。
|
||
|
||
---
|
||
|
||
## 📋 前置要求
|
||
|
||
### 环境要求
|
||
|
||
- **Node.js**: >= 20
|
||
- **pnpm**: >= 9（必须使用 pnpm）
|
||
- **Nginx**: 已安装并运行（用于部署）
|
||
|
||
### 服务器要求
|
||
|
||
- Linux/Unix 服务器
|
||
- 已安装 Nginx
|
||
- 有权限访问服务器文件系统
|
||
|
||
---
|
||
|
||
## 🚀 部署步骤
|
||
|
||
### 1. 构建 H5 版本
|
||
|
||
在项目根目录执行以下命令进行构建：
|
||
|
||
```bash
|
||
# 生产环境构建（推荐）
|
||
pnpm build:h5:prod
|
||
|
||
# 或者使用默认构建命令
|
||
pnpm build:h5
|
||
```
|
||
|
||
构建完成后，文件会输出到 `dist/build/h5` 目录。
|
||
|
||
### 2. 配置环境变量（可选）
|
||
|
||
如果您的应用需要部署在子目录下，或者需要修改其他配置，请编辑 `env/.env.production` 文件：
|
||
|
||
```env
|
||
# 应用标题
|
||
VITE_APP_TITLE=芋道管理后台
|
||
|
||
# 后端 API 地址
|
||
VITE_SERVER_BASEURL=https://your-backend-api.com
|
||
|
||
# H5 路由基础路径
|
||
# 如果部署在根目录，设置为 /
|
||
# 如果部署在子目录（如 /app/），设置为 /app/
|
||
VITE_APP_PUBLIC_BASE=/
|
||
|
||
# 其他配置...
|
||
```
|
||
|
||
**重要提示：**
|
||
- 如果部署在根目录，`VITE_APP_PUBLIC_BASE` 设置为 `/`
|
||
- 如果部署在子目录（如 `/app/`），`VITE_APP_PUBLIC_BASE` 设置为 `/app/`
|
||
- 修改后需要重新构建：`pnpm build:h5:prod`
|
||
|
||
### 3. 上传文件到服务器
|
||
|
||
将 `dist/build/h5` 目录下的所有文件上传到服务器。
|
||
|
||
**方式一：使用 scp 命令**
|
||
|
||
```bash
|
||
# 上传整个目录到服务器
|
||
scp -r dist/build/h5/* user@your-server:/path/to/nginx/html/
|
||
|
||
# 或者上传到子目录
|
||
scp -r dist/build/h5/* user@your-server:/path/to/nginx/html/app/
|
||
```
|
||
|
||
**方式二：使用 rsync 命令（推荐）**
|
||
|
||
```bash
|
||
# 同步文件到服务器
|
||
rsync -avz dist/build/h5/ user@your-server:/path/to/nginx/html/
|
||
|
||
# 或者同步到子目录
|
||
rsync -avz dist/build/h5/ user@your-server:/path/to/nginx/html/app/
|
||
```
|
||
|
||
**方式三：使用 FTP/SFTP 工具**
|
||
|
||
使用 FileZilla、WinSCP 等工具上传文件。
|
||
|
||
### 4. 配置 Nginx
|
||
|
||
#### 4.1 部署在根目录（推荐）
|
||
|
||
1. 复制 `nginx.conf.example` 文件中的第一个 server 配置块
|
||
2. 修改以下配置：
|
||
- `server_name`: 改为您的域名或 IP
|
||
- `root`: 改为实际的文件路径（指向 `dist/build/h5` 目录）
|
||
3. 将配置添加到 Nginx 配置文件（通常在 `/etc/nginx/sites-available/` 或 `/etc/nginx/conf.d/`）
|
||
|
||
**示例配置：**
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name your-domain.com;
|
||
|
||
root /var/www/html;
|
||
index index.html;
|
||
|
||
# 启用 gzip 压缩
|
||
gzip on;
|
||
gzip_vary on;
|
||
gzip_min_length 1024;
|
||
gzip_types text/plain text/css text/xml text/javascript application/x-javascript application/xml+rss application/json application/javascript;
|
||
|
||
# 静态资源缓存
|
||
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
|
||
expires 1y;
|
||
add_header Cache-Control "public, immutable";
|
||
}
|
||
|
||
# Vue Router History 模式支持
|
||
location / {
|
||
try_files $uri $uri/ /index.html;
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 4.2 部署在子目录
|
||
|
||
如果您的应用需要部署在子目录下（如 `/app/`）：
|
||
|
||
1. 确保 `env/.env.production` 中 `VITE_APP_PUBLIC_BASE=/app/`
|
||
2. 重新构建：`pnpm build:h5:prod`
|
||
3. 上传文件到服务器的 `/app/` 目录
|
||
4. 使用 `nginx.conf.example` 中的第二个 server 配置块
|
||
|
||
#### 4.3 配置 API 代理（可选）
|
||
|
||
如果后端 API 需要通过 Nginx 代理，取消注释并修改 API 代理配置：
|
||
|
||
```nginx
|
||
location /api/ {
|
||
proxy_pass http://your-backend-server:port;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
proxy_set_header X-Forwarded-Proto $scheme;
|
||
}
|
||
```
|
||
|
||
### 5. 测试 Nginx 配置
|
||
|
||
```bash
|
||
# 测试 Nginx 配置文件语法
|
||
sudo nginx -t
|
||
|
||
# 如果测试通过，重新加载 Nginx 配置
|
||
sudo nginx -s reload
|
||
|
||
# 或者重启 Nginx
|
||
sudo systemctl restart nginx
|
||
```
|
||
|
||
### 6. 访问应用
|
||
|
||
在浏览器中访问：
|
||
- 如果部署在根目录：`http://your-domain.com`
|
||
- 如果部署在子目录：`http://your-domain.com/app/`
|
||
|
||
---
|
||
|
||
## 🔧 常见问题
|
||
|
||
### 1. 页面刷新后 404 错误
|
||
|
||
**问题：** 刷新页面或直接访问路由时出现 404 错误。
|
||
|
||
**解决方案：** 确保 Nginx 配置了 `try_files` 指令：
|
||
|
||
```nginx
|
||
location / {
|
||
try_files $uri $uri/ /index.html;
|
||
}
|
||
```
|
||
|
||
### 2. 静态资源加载失败
|
||
|
||
**问题：** CSS、JS 等静态资源无法加载。
|
||
|
||
**解决方案：**
|
||
- 检查 `VITE_APP_PUBLIC_BASE` 配置是否正确
|
||
- 检查文件路径是否正确上传
|
||
- 检查 Nginx 的 `root` 配置是否正确
|
||
|
||
### 3. API 请求跨域问题
|
||
|
||
**问题：** 前端请求后端 API 时出现跨域错误。
|
||
|
||
**解决方案：**
|
||
- 在 Nginx 中配置 API 代理（推荐）
|
||
- 或者在后端配置 CORS 允许跨域
|
||
|
||
### 4. 部署在子目录后路由不工作
|
||
|
||
**问题：** 部署在子目录后，路由跳转不正确。
|
||
|
||
**解决方案：**
|
||
- 确保 `env/.env.production` 中 `VITE_APP_PUBLIC_BASE` 设置为正确的子目录路径（如 `/app/`）
|
||
- 重新构建项目
|
||
- 确保 Nginx 配置正确
|
||
|
||
---
|
||
|
||
## 📝 完整部署示例
|
||
|
||
### 示例：部署到根目录
|
||
|
||
```bash
|
||
# 1. 构建项目
|
||
pnpm build:h5:prod
|
||
|
||
# 2. 上传到服务器
|
||
rsync -avz dist/build/h5/ user@server:/var/www/html/
|
||
|
||
# 3. 在服务器上配置 Nginx（参考上面的配置）
|
||
|
||
# 4. 测试并重载 Nginx
|
||
sudo nginx -t
|
||
sudo nginx -s reload
|
||
```
|
||
|
||
### 示例：部署到子目录 `/app/`
|
||
|
||
```bash
|
||
# 1. 修改环境变量
|
||
# 编辑 env/.env.production，设置 VITE_APP_PUBLIC_BASE=/app/
|
||
|
||
# 2. 重新构建
|
||
pnpm build:h5:prod
|
||
|
||
# 3. 上传到服务器子目录
|
||
rsync -avz dist/build/h5/ user@server:/var/www/html/app/
|
||
|
||
# 4. 在服务器上配置 Nginx（使用子目录配置）
|
||
|
||
# 5. 测试并重载 Nginx
|
||
sudo nginx -t
|
||
sudo nginx -s reload
|
||
```
|
||
|
||
---
|
||
|
||
## 🔒 HTTPS 配置（推荐生产环境）
|
||
|
||
生产环境建议使用 HTTPS，可以参考 `nginx.conf.example` 中的 HTTPS 配置示例。
|
||
|
||
使用 Let's Encrypt 免费证书：
|
||
|
||
```bash
|
||
# 安装 certbot
|
||
sudo apt-get install certbot python3-certbot-nginx
|
||
|
||
# 获取证书
|
||
sudo certbot --nginx -d your-domain.com
|
||
|
||
# 证书会自动配置，并设置自动续期
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 相关文档
|
||
|
||
- [项目启动文档](./启动文档.md)
|
||
- [构建文档](./docs/base/11-build.md)
|
||
- [环境变量配置](./docs/base/12-env.md)
|
||
|
||
---
|
||
|
||
## ✅ 检查清单
|
||
|
||
部署前请确认：
|
||
|
||
- [ ] 已构建 H5 版本（`pnpm build:h5:prod`）
|
||
- [ ] 已配置正确的环境变量（特别是 `VITE_APP_PUBLIC_BASE`）
|
||
- [ ] 已上传文件到服务器
|
||
- [ ] 已配置 Nginx（包括 `try_files` 指令）
|
||
- [ ] 已测试 Nginx 配置（`nginx -t`）
|
||
- [ ] 已重载 Nginx 配置
|
||
- [ ] 已测试访问应用
|
||
- [ ] 已测试页面刷新功能
|
||
- [ ] 已测试 API 请求（如果配置了代理）
|
||
|
||
---
|
||
|
||
**部署完成后，您就可以通过浏览器访问您的应用了！** 🎉
|