car-app/H5部署文档.md

# 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 请求（如果配置了代理）

---

**部署完成后，您就可以通过浏览器访问您的应用了！** 🎉