UniApp H5 移动端 Jenkins 自动化部署指南

项目信息

项目名称: RuoYi Office UniApp 移动端
技术栈: UniApp + Vue 3 + Vite 5 + TypeScript 5.8 + UnoCSS + wot-design-uni
包管理器: pnpm（单体项目）
脚手架: unibest 4.x
Git 仓库: git@codeup.aliyun.com:676b69e335730943ed494c52/ruoyi-office/ruoyi-office-uniapp.git
访问地址: http://127.0.0.1/h5

部署架构

Jenkins服务器(140)                    Nginx服务器(127.0.0.1)
┌─────────────────┐                  ┌──────────────────────┐
│  Jenkins容器     │                  │  Nginx容器            │
│  - 拉取代码      │  SSH/Publish     │  - 静态文件服务       │
│  - pnpm install  │  Over SSH        │  - /data/nginx/html/  │
│  - build:h5:prod │ ───────────────> │    h5/                │
│  - 部署文件      │                  │  - location /h5       │
└─────────────────┘                  └──────────────────────┘

前置条件

Jenkins 服务器(140)已部署并运行
Nginx 服务器(127.0.0.1)已部署并运行
Jenkins 已安装 NodeJS Plugin 和 Publish Over SSH Plugin
Jenkins 已配置 SSH 连接到 Nginx 服务器
两台服务器之间网络互通

与 Vben Admin 部署的差异

配置项	ruoyi-office-vben/web-antd	ruoyi-office-uniapp (H5)
项目结构	Monorepo 工作空间	单体项目
包管理器	pnpm (Monorepo)	pnpm (单体)
构建命令	pnpm build	pnpm build:h5:prod
产物目录	apps/web-antd/dist	dist/build/h5
访问路径	/web	/h5
Base 配置	vite.config.mts base	env/.env VITE_APP_PUBLIC_BASE
路由模式	hash	hash (默认)
环境变量	.env.production	env/.env + env/.env.production
工作目录	apps/web-antd	项目根目录
依赖安装	Monorepo 根目录	项目根目录
Nginx 配置	location /web	location /h5

部署步骤

步骤1: 配置环境变量

1.1 配置 Base 路径

编辑 env/.env 文件，设置 H5 部署的 base 路径：

bash

# h5部署网站的base，配置到 manifest.config.ts 里的 h5.router.base
# 如果部署在子路径 /h5/ 下，需要配置为 /h5/
VITE_APP_PUBLIC_BASE=/h5/

说明:

VITE_APP_PUBLIC_BASE 会同时影响 Vite 的 base 配置和 UniApp H5 的 router.base 配置
如果部署在根路径，设置为 /
如果部署在子路径 /h5/，设置为 /h5/
路径末尾必须带 /

1.2 配置后端 API 地址

方案1: 同域 Nginx + 绝对 API 地址（生产默认）

编辑 env/.env 文件：

bash

# 必须带 http(s) 的绝对地址。相对 /admin-api 会让 uni.uploadFile 再拼一层前缀，上传失败。
VITE_SERVER_BASEURL = 'https://oa.example.com/admin-api'

# 生产环境不走 Vite 代理，由入口 Nginx 反代 /admin-api
VITE_APP_PROXY_ENABLE = false

Nginx 仍要反代 /admin-api。切域名后重打 H5，不要用相对路径图省事。

方案2: 直接访问后端（跨域）

编辑 env/.env 文件：

bash

# 后台请求地址（使用绝对路径）
VITE_SERVER_BASEURL = 'http://192.168.30.130:48080/admin-api'

# h5是否需要配置代理
VITE_APP_PROXY_ENABLE = false

注意: 此方案需要后端配置 CORS 允许跨域请求。

1.3 配置生产环境变量

编辑 env/.env.production 文件：

bash

# 变量必须以 VITE_ 为前缀才能暴露给外部读取
NODE_ENV = 'production'
# 是否去除console 和 debugger
VITE_DELETE_CONSOLE = true
# 是否开启sourcemap
VITE_SHOW_SOURCEMAP = false

# 后台请求地址（如果需要覆盖 .env 中的配置）
# VITE_SERVER_BASEURL = 'https://prod.yourdomain.com/admin-api'

步骤2: 配置 Node.js 和 pnpm

与 Vben Admin 部署相同，Jenkins 需要 NodeJS Plugin 提供 Node.js 环境。

使用 Jenkinsfile 自动安装（推荐）

Jenkinsfile 已包含自动安装 pnpm 的逻辑，无需手动操作。

前提条件:

✅ Jenkins 已安装 NodeJS Plugin
✅ Jenkins 已配置 Node.js 工具（名称：node20）
✅ Jenkinsfile 中包含 tools { nodejs 'node20' }

步骤3: 配置 Publish Over SSH

复用已有配置（如果已为 ruoyi-office-vben 配置过）:

Jenkins 系统配置中的 nginx-server SSH 配置可以直接复用。

配置参数:

Name: nginx-server
Hostname: 127.0.0.1
Username: root
Remote Directory: /data/nginx/html
Key: SSH 私钥内容

步骤4: 配置 Nginx

4.1 创建部署目录

bash

mkdir -p /data/nginx/html/h5
chmod 755 /data/nginx/html/h5

4.2 添加 Nginx 配置

方式1: 添加到现有配置文件（推荐）

如果已有 ruoyi-office.conf 统一配置文件，在 server { ... } 块内添加以下 location 配置：

bash

# 编辑现有配置
vi /data/nginx/conf/conf.d/ruoyi-office.conf

在 server { ... } 块内添加：

nginx

# ==================== UniApp H5 移动端 ====================
# 静态资源优先匹配
location ~* ^/h5/.+\.(jpg|jpeg|png|gif|ico|css|js|mjs|svg|woff|woff2|ttf|eot|map|json|mp3|mp4|webm|ogg|wav|flac|aac)$ {
    alias /usr/share/nginx/html/h5;
    try_files $uri =404;
    expires 30d;
    add_header Cache-Control "public, immutable";
    access_log off;
}

# UniApp H5 主配置
location /h5 {
    alias /usr/share/nginx/html/h5;
    index index.html;
    try_files $uri $uri/ /h5/index.html;

    charset utf-8;

    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 image/svg+xml;
}

方式2: 创建独立配置文件

bash

# 将项目中的 uniapp-h5.conf 上传到 Nginx 配置目录
scp uniapp-h5.conf root@127.0.0.1:/data/nginx/conf/conf.d/

注意: 如果创建独立配置文件，需要包含完整的 server 块，可能与现有的 listen 80 冲突，建议使用方式1。

4.3 启用后端 API 代理（推荐）

如果还没有配置 /admin-api 代理（已在 ruoyi-office.conf 中配置则跳过），添加：

nginx

location /admin-api {
    # 代理到后端服务
    # 如果后端在同一服务器，使用 localhost
    # proxy_pass http://localhost:48080;

    # 如果后端在其他服务器，使用实际IP
    proxy_pass http://192.168.30.130:48080;

    # 代理头设置
    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;

    # WebSocket 支持
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    # 超时设置
    proxy_connect_timeout 60s;
    proxy_send_timeout 60s;
    proxy_read_timeout 60s;

    # 缓冲区设置
    proxy_buffer_size 64k;
    proxy_buffers 4 64k;
    proxy_busy_buffers_size 128k;
}

4.4 验证并重新加载 Nginx

bash

# 验证配置
docker exec nginx nginx -t

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

步骤5: 创建 Jenkins Pipeline 任务

登录 Jenkins Web 界面
点击 新建任务
输入任务名称（如：ruoyi-office-uniapp-h5-deploy）
选择 流水线 (Pipeline)
点击 确定
在配置页面：
- Pipeline 定义: 选择 Pipeline script from SCM
- SCM: 选择 Git
- Repository URL: git@codeup.aliyun.com:676b69e335730943ed494c52/ruoyi-office/ruoyi-office-uniapp.git
- Credentials: 选择可以访问 Git 仓库的凭据
- 分支: */main 或 */master（根据实际分支名）
- 脚本路径: Jenkinsfile
点击 保存

步骤6: 执行首次部署

在 Jenkins 任务页面，点击 立即构建
查看构建日志，确认：
- ✅ 拉取代码：代码拉取成功
- ✅ 环境检查：Node、npm、pnpm 版本正常
- ✅ 安装依赖：pnpm install 成功
- ✅ 构建 H5 应用：build:h5:prod 成功，生成 dist/build/h5 目录
- ✅ 部署到 Nginx：文件传输成功
- ✅ 验证部署：显示访问地址
如果构建失败，查看日志排查问题

步骤7: 验证部署

7.1 检查文件是否传输成功

bash

# 在 Nginx 服务器上执行
ls -la /data/nginx/html/h5/

应该看到 index.html、assets/ 等文件。

7.2 访问站点

浏览器访问: http://127.0.0.1/h5

应该能看到 UniApp H5 移动端页面。

7.3 检查 Nginx 日志

bash

docker exec nginx tail -f /var/log/nginx/access.log
docker exec nginx tail -f /var/log/nginx/error.log

环境变量配置说明

UniApp 环境变量加载机制

UniApp (unibest) 项目的环境变量文件位于 env/ 目录下：

env/
├── .env              # 所有环境通用变量（基础配置）
├── .env.development  # 开发环境变量（覆盖 .env）
├── .env.production   # 生产环境变量（覆盖 .env）
└── .env.test         # 测试环境变量（覆盖 .env）

加载优先级: .env.[mode] > .env

关键环境变量

变量名	说明	示例值
`VITE_APP_PUBLIC_BASE`	H5 部署的 base 路径	`/h5/`
`VITE_SERVER_BASEURL`	后端 API 地址	`/admin-api` 或 `http://x.x.x.x:48080/admin-api`
`VITE_APP_PROXY_ENABLE`	是否启用开发代理	`false`（生产环境）
`VITE_APP_PROXY_PREFIX`	代理前缀	`/admin-api`
`VITE_DELETE_CONSOLE`	是否移除 console	`true`（生产环境）
`VITE_SHOW_SOURCEMAP`	是否生成 sourcemap	`false`（生产环境）
`VITE_APP_TITLE`	应用标题	`企业管理一体化平台`
`VITE_UPLOAD_TYPE`	文件上传类型	`server`
`VITE_APP_TENANT_ENABLE`	租户开关	`true`
`VITE_APP_CAPTCHA_ENABLE`	验证码开关	`false`

生产环境推荐配置

env/.env (修改以下关键项):

bash

# 部署在 /h5/ 子路径
VITE_APP_PUBLIC_BASE=/h5/

# 后台请求地址（生产默认绝对路径，须含 http(s)）
VITE_SERVER_BASEURL = 'https://oa.example.com/admin-api'

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

env/.env.production (保持默认即可):

bash

NODE_ENV = 'production'
VITE_DELETE_CONSOLE = true
VITE_SHOW_SOURCEMAP = false

构建命令说明

UniApp 支持多平台构建，本部署方案使用 H5 构建：

命令	说明	产物目录
`pnpm build:h5:prod`	H5 生产环境构建	`dist/build/h5`
`pnpm build:h5`	H5 默认构建	`dist/build/h5`
`pnpm build:h5:test`	H5 测试环境构建	`dist/build/h5`
`pnpm build:mp`	微信小程序构建	`dist/build/mp-weixin`
`pnpm build:app`	APP 构建	`dist/build/app`

Jenkinsfile 默认使用 build:h5:prod（生产环境 H5 构建）。

故障排查

1. pnpm 未安装或找不到

问题: 构建失败，提示 pnpm: command not found

解决方案: 使用 npx pnpm@latest 代替 pnpm（Jenkinsfile 已默认使用此方案）

2. 依赖安装失败

问题: pnpm install 失败

排查步骤:

检查网络连接：

bash

docker exec jenkins ping registry.npmjs.org

检查 pnpm-lock.yaml 是否存在：
bash
```
ls -la pnpm-lock.yaml
```
清理缓存重试：
bash
```
pnpm store prune
pnpm install
```

3. 构建失败 - 产物目录不存在

问题: 构建后找不到 dist/build/h5 目录

原因:

UniApp H5 构建命令不正确
环境变量未正确加载

排查步骤:

bash

# 检查 dist 目录结构
find dist -type d

# 手动执行构建
npx pnpm@latest build:h5:prod

# 检查构建日志中的平台信息
# 应该看到 UNI_PLATFORM -> h5

4. 构建失败 - JavaScript 堆内存溢出

问题: FATAL ERROR: JavaScript heap out of memory

解决方案: 修改 Jenkinsfile 中的 NODE_MEMORY_LIMIT 值：

groovy

environment {
  // 增加到 6GB 或 8GB
  NODE_MEMORY_LIMIT = '6144'  // 或 '8192'
}

5. 页面无法访问 (404)

问题: 访问 http://127.0.0.1/h5 显示 404

排查步骤:

检查 Nginx 配置是否生效:

bash

docker exec nginx nginx -T | grep -A 20 "location /h5"

检查文件是否存在:

bash

docker exec nginx ls -la /usr/share/nginx/html/h5/

检查 Nginx 错误日志:

bash

docker exec nginx tail -f /var/log/nginx/error.log

重新加载 Nginx 配置:
bash
```
docker exec nginx nginx -s reload
```

6. 静态资源 404 或返回 HTML

问题: 页面可以访问，但 JS/CSS 等资源 404

错误信息:

Failed to load module script: Expected a JavaScript-or-Wasm module script but the server responded with a MIME type of "text/html".

解决方案:

检查 VITE_APP_PUBLIC_BASE 配置:

bash

# 确保 env/.env 中配置正确
VITE_APP_PUBLIC_BASE=/h5/

确保 Nginx 静态资源优先匹配:

nginx

# 静态资源的 location 块必须使用正则（优先级更高）
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;
}

重新构建并部署:

bash

# 修改 VITE_APP_PUBLIC_BASE 后需要重新构建
npx pnpm@latest build:h5:prod

7. API 请求失败

问题: 前端页面正常，但 API 请求失败

排查步骤:

检查 VITE_SERVER_BASEURL 配置:

bash

# env/.env 中应该配置为：
VITE_SERVER_BASEURL = 'https://oa.example.com/admin-api'
# 或
VITE_SERVER_BASEURL = 'http://x.x.x.x:48080/admin-api'

检查 Nginx 代理配置:

bash

docker exec nginx nginx -T | grep -A 20 "location /admin-api"

测试后端服务:

bash

curl http://192.168.30.130:48080/admin-api/system/tenant/get-by-website?website=127.0.0.1

8. 移动端适配问题

问题: H5 页面在手机浏览器上显示异常

排查步骤:

检查 index.html 中的 viewport meta 标签是否正确
使用浏览器开发者工具的移动端模拟器测试
检查 CSS 是否使用了响应式单位（rpx、vw、vh）

配置文件说明

文件	说明
`Jenkinsfile`	Jenkins Pipeline 配置，定义构建和部署流程
`env/.env`	通用环境变量（base路径、API地址等）
`env/.env.production`	生产环境变量（覆盖通用配置）
`vite.config.ts`	Vite 构建配置
`manifest.config.ts`	UniApp 清单配置（H5 router base）
`package.json`	项目依赖和构建脚本

注意事项

环境变量目录:
- UniApp 项目的环境变量文件在 env/ 子目录下，不在项目根目录
- Vite 配置中已指定 envDir: './env'
Base 路径:
- 通过 VITE_APP_PUBLIC_BASE 统一管理
- 该变量同时影响 Vite base 和 UniApp H5 router.base
- 路径末尾必须带 /（如 /h5/）
构建命令:
- 使用 build:h5:prod 而非 build（后者默认也是 H5）
- build:h5:prod 等价于 uni build --mode production
- 产物目录固定为 dist/build/h5
路由模式:
- UniApp H5 默认使用 hash 路由（/#/）
- hash 路由不需要 Nginx 的 try_files 配置也能工作
- 但建议保留 try_files 以兼容 history 路由模式
单体项目:
- 与 Vben Admin 的 Monorepo 不同，UniApp 是单体项目
- 无需构建内部依赖包，直接 pnpm install + pnpm build:h5:prod
pnpm 版本:
- 项目要求 pnpm >= 9
- package.json 中指定 "packageManager": "pnpm@10.10.0"
- 使用 npx pnpm@latest 可自动获取最新版本
Node.js 版本:
- 项目要求 Node.js >= 20
- Jenkins 配置的 node20 工具满足要求

统一配置方案（推荐）

如果同时部署了 Vben Admin 管理后台 和 UniApp H5 移动端，建议使用统一的 Nginx 配置文件。

统一配置示例

在 ruoyi-office.conf 中同时包含所有应用的配置：

nginx

server {
    listen 80;
    server_name _;

    # ==================== Vben Admin 管理后台 ====================
    location ~* ^/web/.+\.(jpg|jpeg|png|gif|ico|css|js|mjs|svg|woff|woff2|ttf|eot|map|json)$ {
        alias /usr/share/nginx/html/web;
        try_files $uri =404;
        expires 30d;
        add_header Cache-Control "public, immutable";
        access_log off;
    }

    location /web {
        alias /usr/share/nginx/html/web;
        index index.html;
        try_files $uri $uri/ /web/index.html;
        charset utf-8;
    }

    # ==================== UniApp H5 移动端 ====================
    location ~* ^/h5/.+\.(jpg|jpeg|png|gif|ico|css|js|mjs|svg|woff|woff2|ttf|eot|map|json|mp3|mp4|webm|ogg|wav|flac|aac)$ {
        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;
    }

    # ==================== 后端 API 代理 ====================
    location /admin-api {
        proxy_pass http://192.168.30.130:48080;
        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;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }

    # ==================== 全局 Gzip ====================
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_comp_level 6;
    gzip_types text/plain text/css text/xml text/javascript application/x-javascript application/xml+rss application/json application/javascript image/svg+xml;
}

访问地址

统一配置后的访问地址：

Vben Admin 管理后台: http://127.0.0.1/web
UniApp H5 移动端: http://127.0.0.1/h5
后端 API: http://127.0.0.1/admin-api

后续维护

自动触发部署

可以配置 Git Webhook，在代码推送时自动触发 Jenkins 构建：

在 Git 仓库设置中添加 Webhook
Webhook URL: http://140:8080/github-webhook/（根据实际 Jenkins 配置）
触发事件: Push events
分支过滤: main 或 master

手动触发部署

在 Jenkins 任务页面点击 立即构建 即可。

查看部署历史

在 Jenkins 任务页面可以查看所有构建历史和日志。

参考文档

成功部署示例

访问 http://127.0.0.1/h5 应该看到：

✅ UniApp H5 移动端页面
✅ 页面样式正常显示
✅ 静态资源加载正常
✅ 路由跳转正常工作
✅ API 请求正常返回数据
✅ 移动端适配正常

如有问题，请参考故障排查部分或查看 Jenkins 构建日志。

UniApp H5 移动端 Jenkins 自动化部署指南 ​

项目信息 ​

部署架构 ​

前置条件 ​

与 Vben Admin 部署的差异 ​

部署步骤 ​

步骤1: 配置环境变量 ​

1.1 配置 Base 路径 ​

1.2 配置后端 API 地址 ​

方案1: 同域 Nginx + 绝对 API 地址（生产默认） ​

方案2: 直接访问后端（跨域） ​

1.3 配置生产环境变量 ​

步骤2: 配置 Node.js 和 pnpm ​

使用 Jenkinsfile 自动安装（推荐） ​

步骤3: 配置 Publish Over SSH ​

步骤4: 配置 Nginx ​

4.1 创建部署目录 ​

4.2 添加 Nginx 配置 ​

4.3 启用后端 API 代理（推荐） ​

4.4 验证并重新加载 Nginx ​

步骤5: 创建 Jenkins Pipeline 任务 ​

步骤6: 执行首次部署 ​

步骤7: 验证部署 ​

7.1 检查文件是否传输成功 ​

7.2 访问站点 ​

7.3 检查 Nginx 日志 ​

环境变量配置说明 ​

UniApp 环境变量加载机制 ​

关键环境变量 ​

生产环境推荐配置 ​

构建命令说明 ​

故障排查 ​

1. pnpm 未安装或找不到 ​

2. 依赖安装失败 ​

3. 构建失败 - 产物目录不存在 ​

4. 构建失败 - JavaScript 堆内存溢出 ​

5. 页面无法访问 (404) ​

6. 静态资源 404 或返回 HTML ​

7. API 请求失败 ​

8. 移动端适配问题 ​

配置文件说明 ​

注意事项 ​

统一配置方案（推荐） ​

统一配置示例 ​

访问地址 ​

后续维护 ​

自动触发部署 ​

手动触发部署 ​

查看部署历史 ​

参考文档 ​

成功部署示例 ​

UniApp H5 移动端 Jenkins 自动化部署指南

项目信息

部署架构

前置条件

与 Vben Admin 部署的差异

部署步骤

步骤1: 配置环境变量

1.1 配置 Base 路径

1.2 配置后端 API 地址

方案1: 同域 Nginx + 绝对 API 地址（生产默认）

方案2: 直接访问后端（跨域）

1.3 配置生产环境变量

步骤2: 配置 Node.js 和 pnpm

使用 Jenkinsfile 自动安装（推荐）

步骤3: 配置 Publish Over SSH

步骤4: 配置 Nginx

4.1 创建部署目录

4.2 添加 Nginx 配置

4.3 启用后端 API 代理（推荐）

4.4 验证并重新加载 Nginx

步骤5: 创建 Jenkins Pipeline 任务

步骤6: 执行首次部署

步骤7: 验证部署

7.1 检查文件是否传输成功

7.2 访问站点

7.3 检查 Nginx 日志

环境变量配置说明

UniApp 环境变量加载机制

关键环境变量

生产环境推荐配置

构建命令说明

故障排查

1. pnpm 未安装或找不到

2. 依赖安装失败

3. 构建失败 - 产物目录不存在

4. 构建失败 - JavaScript 堆内存溢出

5. 页面无法访问 (404)

6. 静态资源 404 或返回 HTML

7. API 请求失败

8. 移动端适配问题

配置文件说明

注意事项

统一配置方案（推荐）

统一配置示例

访问地址

后续维护

自动触发部署

手动触发部署

查看部署历史

参考文档

成功部署示例