H5 打包与部署运行指南

本指南记录了基于 uni-app (Vue 3 + Vite) 项目在 H5 端的打包以及线上 Nginx 部署全流程。

---

一、 打包前配置检查

打包生成环境静态文件前，需先配置接口地址与基础路由路径。

1. 配置环境变量

项目环境变量配置文件位于 env/ 目录下：

• .env：通用环境配置
• .env.production：生产环境配置

重点检查并确认以下字段：

# 生产环境 API 接口后端地址
VITE_SERVER_BASEURL = 'https://your-domain.com/tduck-api'

# 站点域名 (PC端/前端域名)
VITE_WEB_BASEURL = 'https://your-domain.com'

# 部署基础路径 (如果部署在根目录填 '/'；若部署在二级目录如 https://domain.com/h5/，则填 '/h5/')
VITE_APP_PUBLIC_BASE = '/'

---

二、 H5 打包命令与操作

方式 1：使用命令行打包（推荐）

在项目根目录下运行打包命令：

# 使用 pnpm 打包 H5 端
pnpm build:h5

打包输出目录：

打包成功后，编译静态文件将生成在：

dist/build/h5/
├── assets/         # 编译后的 JS、CSS 资源文件
├── static/         # 图片及静态素材
└── index.html      # 入口 HTML 文件

三、 线上服务器部署 (Nginx 配置)

将 dist/build/h5 目录下的所有文件上传至服务器目标路径（如 /usr/share/nginx/html/h5）。

Nginx 完整配置文件示例：

server {
    listen       80;
    server_name  your-domain.com; # 您的域名或服务器IP

    # 根目录模式配置
    location / {  
      # 静态文件资源
        root   /usr/share/nginx/html/h5; 
        index  index.html index.htm;
        
        # 解决前端 History 路由模式刷新 404 问题
        try_files $uri $uri/ /index.html;
    }

    # API 接口反向代理 (解决前端跨域问题)
    location /tduck-api/ {
        proxy_pass http://127.0.0.1:8888/tduck-api/; # 后端真实服务地址
        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;
    }

    # 静态资源缓存优化
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf)$ {
        root      /usr/share/nginx/html/h5;
        expires   7d;
        add_header Cache-Control "public, no-transform";
    }

    # 开启 Gzip 压缩
    gzip on;
    gzip_min_length 1k;
    gzip_comp_level 6;
    gzip_types text/plain text/css application/json application/javascript application/x-javascript text/xml application/xml application/xml+rss text/javascript;
}

配置完成后重启或重载 Nginx：

nginx -t
nginx -s reload

宝塔部署

如果使用宝塔进行部署，配置好项目后上传静态资源文件。在配置文件中加入

# API 接口反向代理 (解决前端跨域问题)
    location /tduck-api/ {
        proxy_pass http://127.0.0.1:8888/tduck-api/; # 后端真实服务地址
        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;
    }

---

四、 常见问题排查

现象	可能原因	解决办法
刷新页面 404	HTML5 History 路由模式下无服务端路由重定向	在 Nginx 配置中增加 try_files $uri $uri/ /index.html;
JS/CSS 资源 404	打包基础路径与实际部署子目录不一致	若部署在子目录（如 /h5/），请调整 .env 中 VITE_APP_PUBLIC_BASE = '/h5/' 后重新打包
接口跨域 (CORS Error)	接口跨域且未配置代理	通过 Nginx 反向代理配置 location /tduck-api/ 或在后端响应头中开启 CORS
微信网页授权失败	网页域名未认证	在微信公众号后台设置中的“网页授权域名”和“JS接口安全域名”添加部署域名