car-app/H5部署文档.md

H5 版本部署文档

本文档介绍如何将项目编译成 H5 版本并部署到服务器，通过 Nginx 运行和代理访问。

---

📋 前置要求

环境要求

• Node.js: >= 20
• pnpm: >= 9（必须使用 pnpm）
• Nginx: 已安装并运行（用于部署）

服务器要求

• Linux/Unix 服务器
• 已安装 Nginx
• 有权限访问服务器文件系统

---

🚀 部署步骤

1. 构建 H5 版本

在项目根目录执行以下命令进行构建：

# 生产环境构建（推荐）
pnpm build:h5:prod

# 或者使用默认构建命令
pnpm build:h5

构建完成后，文件会输出到 dist/build/h5 目录。

2. 配置环境变量（可选）

如果您的应用需要部署在子目录下，或者需要修改其他配置，请编辑 env/.env.production 文件：

# 应用标题
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 命令

# 上传整个目录到服务器
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 命令（推荐）

# 同步文件到服务器
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/）

示例配置：

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 代理配置：

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 配置

# 测试 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 指令：

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 配置正确

---

📝 完整部署示例

示例：部署到根目录

# 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/

# 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 免费证书：

# 安装 certbot
sudo apt-get install certbot python3-certbot-nginx

# 获取证书
sudo certbot --nginx -d your-domain.com

# 证书会自动配置，并设置自动续期

---

📚 相关文档

• 项目启动文档
• 构建文档
• 环境变量配置

---

✅ 检查清单

部署前请确认：

• 已构建 H5 版本（pnpm build:h5:prod）
• 已配置正确的环境变量（特别是 VITE_APP_PUBLIC_BASE）
• 已上传文件到服务器
• 已配置 Nginx（包括 try_files 指令）
• 已测试 Nginx 配置（nginx -t）
• 已重载 Nginx 配置
• 已测试访问应用
• 已测试页面刷新功能
• 已测试 API 请求（如果配置了代理）

---

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