UniApp H5 移动端部署操作清单

部署前检查清单

Jenkins 服务器(140)

[ ] Jenkins 容器正常运行
[ ] NodeJS Plugin 已安装
[ ] Publish Over SSH Plugin 已安装
[ ] Node.js 工具已配置（名称：node20，版本 >= 20）
[ ] SSH 服务器配置已添加（nginx-server）
[ ] 可以访问 Git 仓库（凭据已配置）

Nginx 服务器(127.0.0.1)

[ ] Nginx 容器正常运行
[ ] 部署目录已创建：/data/nginx/html/h5
[ ] 目录权限正确：chmod 755 /data/nginx/html/h5
[ ] Nginx 配置已添加 location /h5
[ ] Nginx 配置语法验证通过：docker exec nginx nginx -t
[ ] SSH 连接正常（Jenkins 可以连接）

代码仓库

[ ] env/.env 已配置 VITE_APP_PUBLIC_BASE=/h5/
[ ] env/.env 已配置 VITE_SERVER_BASEURL（API 地址）
[ ] Jenkinsfile 已提交到仓库根目录
[ ] Git 凭据已配置（如需要）

部署步骤

第一步：配置环境变量

bash

# 在代码仓库中编辑 env/.env 文件

# 1. 配置 H5 部署路径（路径末尾必须带 /）
VITE_APP_PUBLIC_BASE=/h5/

# 2. 配置后端 API 地址（生产默认绝对路径，须含 http(s)；相对 /admin-api 会导致移动端上传叠前缀失败）
VITE_SERVER_BASEURL = 'https://oa.example.com/admin-api'
# 或直连后端：VITE_SERVER_BASEURL = 'http://192.168.30.130:48080/admin-api'

# 3. 生产环境不需要代理
VITE_APP_PROXY_ENABLE = false

检查点: ✅ 环境变量配置正确

第二步：配置 Nginx

bash

# 在 Nginx 服务器(127.0.0.1)上执行

# 1. 创建部署目录
mkdir -p /data/nginx/html/h5
chmod 755 /data/nginx/html/h5

# 2. 编辑 Nginx 配置文件
# 方式A：添加到已有的 ruoyi-office.conf（推荐，与 Vben Admin 共用一个 server 块）
vi /data/nginx/conf/conf.d/ruoyi-office.conf

# 方式B：创建独立配置文件（注意不要与现有 listen 80 冲突）
vi /data/nginx/conf/conf.d/uniapp-h5.conf

# 3. 添加以下配置（参考 uniapp-h5.conf）
# location ~* ^/h5/.+\.(jpg|jpeg|png|gif|ico|css|js|mjs|svg|woff|woff2|ttf|eot|map|json)$ {
#     alias /usr/share/nginx/html/h5;
#     try_files $uri =404;
#     expires 30d;
#     add_header Cache-Control "public, immutable";
#     access_log off;
# }
#
# location /h5 {
#     alias /usr/share/nginx/html/h5;
#     index index.html;
#     try_files $uri $uri/ /h5/index.html;
#     charset utf-8;
# }

# 4. 验证配置
docker exec nginx nginx -t

# 5. 重新加载配置
docker exec nginx nginx -s reload

检查点:

✅ 配置语法验证通过
✅ Nginx 重新加载成功

第三步：创建 Jenkins Pipeline 任务

登录 Jenkins Web 界面：http://140:8080
点击 新建任务
配置任务：
- 任务名称: ruoyi-office-uniapp-h5-deploy
- 类型: 流水线 (Pipeline)
Pipeline 配置：
- 定义: Pipeline script from SCM
- SCM: Git
- 仓库 URL: git@codeup.aliyun.com:676b69e335730943ed494c52/ruoyi-office/ruoyi-office-uniapp.git
- 分支: */main 或 */master
- 脚本路径: Jenkinsfile
点击 保存

检查点: ✅ Jenkins 任务创建成功

第四步：执行首次部署

在 Jenkins 任务页面，点击 立即构建
查看构建日志，确认各阶段成功：
- ✅ 1. 拉取代码
- ✅ 2. 环境检查
- ✅ 3. 安装依赖
- ✅ 4. 构建 H5 应用
- ✅ 5. 部署到 Nginx
- ✅ 6. 验证部署
等待构建完成（预计 3-8 分钟，首次构建时间较长）

检查点: ✅ 构建状态显示成功（绿色）

第五步：验证部署

bash

# 在 Nginx 服务器(127.0.0.1)上执行

# 1. 检查文件是否存在
ls -la /data/nginx/html/h5/
# 应该看到 index.html、assets/ 等文件

# 2. 检查文件数量
find /data/nginx/html/h5/ -type f | wc -l
# 应该有多个文件

# 3. 检查 index.html 内容
head -n 20 /data/nginx/html/h5/index.html
# 应该看到 HTML 内容

# 4. 测试访问
curl -I http://localhost/h5/
# 应该返回 HTTP/1.1 200 OK

检查点:

✅ 文件已传输到服务器
✅ index.html 存在
✅ 本地访问返回 200

第六步：浏览器访问验证

打开浏览器
访问：http://127.0.0.1/h5
验证：
- ✅ 页面正常显示（UniApp H5 移动端页面）
- ✅ 样式正常加载（无样式错乱）
- ✅ 静态资源正常（无 404 错误）
- ✅ 控制台无错误（F12 查看）
- ✅ 移动端适配正常（使用手机模式查看）

检查点: ✅ 应用可以正常访问和使用

部署后验证清单

功能验证

[ ] 登录页面显示正常
[ ] 可以输入用户名密码
[ ] 图片/图标正常显示
[ ] CSS 样式正常加载
[ ] JavaScript 正常执行
[ ] 路由跳转正常工作
[ ] API 请求正常（如已配置后端）
[ ] 移动端触摸操作正常
[ ] 页面在不同手机屏幕尺寸下显示正常

性能验证

[ ] 首屏加载时间 < 3 秒
[ ] 静态资源缓存生效（查看 Response Headers 中的 Cache-Control）
[ ] Gzip 压缩生效（查看 Content-Encoding: gzip）

日志检查

bash

# Nginx 访问日志
docker exec nginx tail -f /var/log/nginx/access.log

# Nginx 错误日志
docker exec nginx tail -f /var/log/nginx/error.log

# Jenkins 构建日志
# 在 Jenkins Web 界面查看

常见问题快速修复

问题1: 页面 404

bash

# 检查 Nginx 配置
docker exec nginx nginx -T | grep -A 10 "location /h5"

# 如果没有配置，添加后重新加载
docker exec nginx nginx -s reload

问题2: 静态资源 404 或返回 HTML

bash

# 检查 VITE_APP_PUBLIC_BASE 配置
cat env/.env | grep VITE_APP_PUBLIC_BASE
# 应该显示: VITE_APP_PUBLIC_BASE=/h5/

# 如果配置不正确，修改后需要重新构建部署

问题3: 文件未传输

bash

# 检查 Jenkins 日志中的传输信息
# 查看是否有 "SSH: Transferred X file(s)" 消息

# 检查 SSH 连接
# Jenkins 系统配置 -> Publish over SSH -> Test Configuration

问题4: 构建产物目录不存在

bash

# UniApp H5 构建产物在 dist/build/h5 目录
# 检查构建日志是否有错误

# 手动尝试构建
cd ruoyi-office-uniapp
npx pnpm@latest install
npx pnpm@latest build:h5:prod
ls -la dist/build/h5/

问题5: API 请求失败

bash

# 检查后端 API 代理配置
docker exec nginx nginx -T | grep -A 10 "location /admin-api"

# 测试后端服务
curl http://192.168.30.130:48080/admin-api/system/tenant/get-by-website?website=127.0.0.1

回滚操作

如果部署出现问题，可以快速回滚：

bash

# 在 Nginx 服务器上执行

# 1. 备份当前版本（如有）
mv /data/nginx/html/h5 /data/nginx/html/h5.backup.$(date +%Y%m%d_%H%M%S)

# 2. 恢复上一个版本
mv /data/nginx/html/h5.backup.YYYYMMDD_HHMMSS /data/nginx/html/h5

# 3. 重新加载 Nginx
docker exec nginx nginx -s reload

后续维护

自动部署

配置 Git Webhook 实现代码推送自动部署：

Git 仓库设置 -> Webhooks
URL: http://140:8080/github-webhook/
触发事件: Push events
分支: main/master

监控

建议配置以下监控：

[ ] Jenkins 构建通知（邮件/企业微信）
[ ] Nginx 访问日志监控
[ ] 应用性能监控（APM）
[ ] 错误日志告警

定期检查

[ ] 每周检查 Jenkins 构建历史
[ ] 每月检查 Nginx 日志
[ ] 定期更新依赖版本
[ ] 定期备份配置文件

部署成功标志

✅ 所有检查项通过 ✅ 浏览器可以访问 http://127.0.0.1/h5 ✅ 页面显示正常，无错误 ✅ Jenkins 构建历史显示成功（绿色） ✅ 移动端适配正常

恭喜！UniApp H5 移动端部署成功！ 🎉

UniApp H5 移动端部署操作清单 ​

部署前检查清单 ​

Jenkins 服务器(140) ​

Nginx 服务器(127.0.0.1) ​

代码仓库 ​

部署步骤 ​

第一步：配置环境变量 ​

第二步：配置 Nginx ​

第三步：创建 Jenkins Pipeline 任务 ​

第四步：执行首次部署 ​

第五步：验证部署 ​

第六步：浏览器访问验证 ​

部署后验证清单 ​

功能验证 ​

性能验证 ​

日志检查 ​

常见问题快速修复 ​

问题1: 页面 404 ​

问题2: 静态资源 404 或返回 HTML ​

问题3: 文件未传输 ​

问题4: 构建产物目录不存在 ​

问题5: API 请求失败 ​

回滚操作 ​

后续维护 ​

自动部署 ​

监控 ​

定期检查 ​

部署成功标志 ​

UniApp H5 移动端部署操作清单

部署前检查清单

Jenkins 服务器(140)

Nginx 服务器(127.0.0.1)

代码仓库

部署步骤

第一步：配置环境变量

第二步：配置 Nginx

第三步：创建 Jenkins Pipeline 任务

第四步：执行首次部署

第五步：验证部署

第六步：浏览器访问验证

部署后验证清单

功能验证

性能验证

日志检查

常见问题快速修复

问题1: 页面 404

问题2: 静态资源 404 或返回 HTML

问题3: 文件未传输

问题4: 构建产物目录不存在

问题5: API 请求失败

回滚操作

后续维护

自动部署

监控

定期检查

部署成功标志