若依 B 端从浏览器访问升级为 Windows 安装包交付流程

1. 文档目的

本文记录本项目将开源若依 B 端从默认的"浏览器访问 Vue 管理后台"方式，升级为"Windows 桌面安装包交付"方式的完整流程。

当前已验证通过的目标效果是：

测试人员下载一个 Windows 安装器 .exe。
双击安装后，桌面出现 Appliance Desktop 应用图标。
用户点击桌面图标后打开独立应用窗口。
应用窗口内加载若依 Vue 前端界面。
前端直接访问一体机或测试服务器上的 Java 后端 API。
用户全程不需要手动打开浏览器。
应用可以从 Windows 应用列表正常卸载。

绿色 zip 包曾作为中间验证环节使用，但当前正式测试交付方案以 Windows 安装包为准。

2. 方案背景

开源若依 Vue 管理后台的常见使用方式是：

后端 Java 服务部署到服务器。
Vue 前端构建后部署到 Nginx 或 Web 容器。
用户通过浏览器访问后台地址。

这种方式适合通用 Web 管理后台，但在一体机或客户现场交付场景里，会遇到一些体验和运维问题：

用户需要记住浏览器访问地址。
不同测试人员的浏览器环境不一致。
地址栏、浏览器缓存、下载策略等会影响体验。
客户更容易理解"安装一个应用，然后从桌面打开"。
售后分发时，希望只给测试人员一个明确的安装包。

因此，本项目采用 Electron 将若依 Vue 前端包装成 Windows 桌面应用，再使用 electron-builder 生成 NSIS 安装包。

3. 最终使用方式

后端部署方式保持不变：

text 复制代码

Java 后端 + MySQL/MariaDB + Redis

后端需要能被测试电脑访问，例如：

text 复制代码

http://测试服务器IP:8080/captchaImage

桌面端交付方式变为：

text 复制代码

Appliance Desktop Setup-YYYYMMDD.exe

测试人员操作：

双击安装包。
安装完成后，桌面出现 Appliance Desktop 图标。
双击桌面图标打开客户端。
首次启动填写后端地址：

text 复制代码

http://测试服务器IP:8080

使用测试账号登录：

text 复制代码

admin / admin123

注意：

测试人员电脑必须能访问测试服务器的 8080 端口。
防火墙、安全组、局域网策略需要放开对应访问。
桌面安装包只包含前端桌面客户端，不包含 Java 后端、MySQL/MariaDB、Redis。

4. 技术架构

整体结构如下：

text 复制代码

Windows 桌面应用
  └─ Electron 主进程
      └─ BrowserWindow
          └─ 若依 Vue 前端 dist
              └─ Axios 请求一体机后端 API

测试服务器 / 一体机
  ├─ Java 后端
  ├─ MySQL 或 MariaDB
  └─ Redis

关键点：

Electron 不替代后端，只负责提供独立桌面窗口和本地配置能力。
Vue 前端仍然是原有若依 B 端界面。
API 地址由用户首次启动时填写，并保存到 Electron 的 userData 目录。
后续启动时，客户端会自动读取本地保存的后端地址并探测 /captchaImage。

5. 项目目录

本文涉及的主要目录如下：

text 复制代码

C:\Users\WD\Desktop\test-project\test-project\Project
├─ web\RuoYi-Vue3                 # 若依 Vue3 前端 + Electron 桌面端
├─ sever\RuoYi-Vue                # 若依 Java 后端
└─ deploy\packages                # 桌面端安装包交付目录

前端工程目录：

text 复制代码

C:\Users\WD\Desktop\test-project\test-project\Project\web\RuoYi-Vue3

安装包输出目录：

text 复制代码

C:\Users\WD\Desktop\test-project\test-project\Project\deploy\packages

6. Electron 入口

当前项目已在前端工程中配置 Electron：

text 复制代码

web/RuoYi-Vue3/electron/main.cjs
web/RuoYi-Vue3/electron/preload.cjs

main.cjs 负责：

创建独立桌面窗口。
加载开发环境地址或生产环境 dist/index.html。
读取和写入一体机后端地址配置。
控制外部链接不要直接在桌面窗口内乱跳转。

preload.cjs 负责：

通过 contextBridge 暴露安全的配置读写接口。
让 Vue 前端可以读取和保存后端 API 地址。

7. package.json 关键配置

前端工程的 package.json 中，关键脚本如下：

json 复制代码

{
  "scripts": {
    "build:web": "vite build",
    "build:desktop": "npm run build:web && electron-builder --win nsis && node scripts/stage-desktop-installer.cjs",
    "build:installer": "npm run build:web && electron-builder --win nsis && node scripts/stage-desktop-installer.cjs",
    "pack:win": "npm run build:web && electron-builder --win --dir"
  }
}

推荐日常打安装包使用：

powershell 复制代码

npm.cmd run build:installer

说明：

build:web 先构建 Vue 前端，生成 dist。
electron-builder --win nsis 再构建 Windows NSIS 安装包。
stage-desktop-installer.cjs 最后把安装器复制到 deploy/packages 并加上日期。

Windows PowerShell 下建议使用 npm.cmd，不要直接使用 npm。某些机器会因为执行策略禁止加载 npm.ps1，导致命令被拦截。

8. electron-builder 配置

当前安装包使用 electron-builder 的 NSIS target：

json 复制代码

{
  "build": {
    "appId": "com.appliance.desktop",
    "productName": "Appliance Desktop",
    "directories": {
      "output": "release"
    },
    "files": [
      "dist/**/*",
      "electron/**/*",
      "package.json"
    ],
    "win": {
      "target": [
        {
          "target": "nsis",
          "arch": ["x64"]
        }
      ],
      "artifactName": "${productName} Setup ${version}.${ext}"
    },
    "nsis": {
      "oneClick": true,
      "perMachine": false,
      "allowElevation": false,
      "createDesktopShortcut": true,
      "createStartMenuShortcut": true,
      "shortcutName": "Appliance Desktop",
      "runAfterFinish": true,
      "deleteAppDataOnUninstall": false
    }
  }
}

配置含义：

target: nsis：生成 Windows 安装器。
arch: x64：构建 64 位 Windows 客户端。
oneClick: true：一键安装，减少测试人员操作。
perMachine: false：用户级安装，不要求管理员权限。
allowElevation: false：不主动申请提权。
createDesktopShortcut: true：安装后创建桌面快捷方式。
createStartMenuShortcut: true：安装后创建开始菜单快捷方式。
runAfterFinish: true：安装完成后可直接启动应用。
deleteAppDataOnUninstall: false：卸载时不主动删除用户配置，避免误删后端地址等本地配置。

9. 安装包归档脚本

脚本位置：

text 复制代码

web/RuoYi-Vue3/scripts/stage-desktop-installer.cjs

作用：

从 release 目录查找 electron-builder 生成的安装器。
复制到项目统一交付目录 deploy/packages。
按日期命名为：

text 复制代码

Appliance Desktop Setup-YYYYMMDD.exe

例如本次测试通过的产物：

text 复制代码

C:\Users\WD\Desktop\test-project\test-project\Project\deploy\packages\Appliance Desktop Setup-20260805.exe

10. 打包流程

进入前端工程目录：

powershell 复制代码

cd C:\Users\WD\Desktop\test-project\test-project\Project\web\RuoYi-Vue3

执行安装包构建：

powershell 复制代码

npm.cmd run build:installer

成功后应看到类似输出：

text 复制代码

vite build
built in xx.xx s

electron-builder
building target=nsis file=release\Appliance Desktop Setup 3.9.2.exe

Staged installer: C:\Users\WD\Desktop\test-project\test-project\Project\deploy\packages\Appliance Desktop Setup-YYYYMMDD.exe

最终交付文件：

text 复制代码

C:\Users\WD\Desktop\test-project\test-project\Project\deploy\packages\Appliance Desktop Setup-YYYYMMDD.exe

11. 分发给同事测试

当前正式测试方案只需要发送安装器 .exe：

text 复制代码

Appliance Desktop Setup-YYYYMMDD.exe

可以通过以下方式分发：

企业微信或钉钉直接发送。
如果聊天工具拦截 .exe，可以压缩成 zip 再发送。
如果仍然拦截，可以上传到内网共享盘、NAS、网盘或测试服务器下载目录。

发给测试人员时，建议附带说明：

text 复制代码

测试客户端安装方式：

1. 双击 Appliance Desktop Setup-YYYYMMDD.exe 安装。
2. 安装完成后，桌面会出现 Appliance Desktop 图标。
3. 双击桌面图标打开客户端。
4. 首次启动填写后端地址：
   http://测试服务器IP:8080
5. 登录账号：
   admin / admin123

注意：
- 测试电脑必须能访问测试服务器的 8080 端口。
- 如果 Windows 提示未知发布者，选择"更多信息" -> "仍要运行"。
- 这个安装包只包含桌面客户端，不包含后端、数据库、Redis。
- 后端必须已经部署好，并能访问：
  http://测试服务器IP:8080/captchaImage

12. 测试验收流程

12.1 后端连通性测试

在测试电脑浏览器或命令行确认后端可访问：

text 复制代码

http://测试服务器IP:8080/captchaImage

如果不能访问，先检查：

Java 后端是否启动。
服务器防火墙是否放开 8080。
云服务器安全组是否放开 8080。
测试电脑和服务器是否处在可互通网络中。

12.2 安装测试

测试步骤：

双击安装器。
等待安装完成。
检查桌面是否出现 Appliance Desktop 图标。
检查开始菜单是否出现 Appliance Desktop。

验收标准：

安装过程无报错。
无需手动解压文件。
无需管理员权限即可完成用户级安装。

12.3 启动测试

测试步骤：

双击桌面 Appliance Desktop。
确认打开独立桌面窗口。
首次启动时填写后端地址。
点击连接。

验收标准：

应用窗口正常打开。
不需要手动打开浏览器。
后端地址保存成功。
可进入登录页。

12.4 登录测试

测试账号：

text 复制代码

admin / admin123

验收标准：

验证码可以加载。
登录请求正常发送到测试后端。
登录成功后进入若依 B 端首页。

12.5 卸载测试

测试步骤：

打开 Windows 应用列表。
找到 Appliance Desktop。
点击卸载。

验收标准：

应用可以正常卸载。
主程序文件被移除。
Windows 应用列表中不再显示该应用。

本项目当前测试结果：

text 复制代码

下载、安装、启动、卸载均已验证通过。

13. 常见问题

13.1 npm 命令被 PowerShell 拦截

现象：

text 复制代码

无法加载文件 npm.ps1，因为在此系统上禁止运行脚本

处理方式：

使用：

powershell 复制代码

npm.cmd run build:installer

不要直接使用：

powershell 复制代码

npm run build:installer

13.2 electron-builder 下载超时

现象：

text 复制代码

connect ETIMEDOUT 20.205.243.166:443

原因：

electron-builder 在构建安装包时可能需要下载 Electron、NSIS 或相关构建资源。该错误通常是访问 GitHub 资源超时，不是 Vue 构建失败。

处理方式：

直接重试构建。
更换网络。
配置代理。
复用已经成功下载过的本地缓存。

判断标准：

如果只看到 vite build built，但后面 electron-builder 报 ETIMEDOUT，说明前端构建成功，安装包没有成功生成。
如果最后看到 Staged installer: ...Appliance Desktop Setup-YYYYMMDD.exe，说明安装包生成成功。

13.3 npm 和 pnpm 如何选择

当前项目使用 package-lock.json，说明依赖主要由 npm 管理。

本次安装包链路已经验证通过的命令是：

powershell 复制代码

npm.cmd run build:installer

如果仅为解决 electron-builder 下载超时，不建议切换 pnpm，因为超时发生在 electron-builder 下载资源阶段，换包管理器通常不能解决网络问题。

如后续团队决定切换 pnpm，需要统一执行：

powershell 复制代码

pnpm install
pnpm run build:installer

并统一提交 pnpm-lock.yaml，避免 npm 和 pnpm 混用导致依赖锁文件混乱。

13.4 Windows 提示未知发布者

原因：

当前第一版安装包未配置企业代码签名证书。

测试阶段处理方式：

text 复制代码

更多信息 -> 仍要运行

正式客户交付建议：

申请或购买代码签名证书。
在 electron-builder 中配置 Windows 签名。
避免客户电脑频繁出现安全提示。

13.5 安装后连接不上后端

优先检查：

填写地址是否正确，例如：

text 复制代码

http://测试服务器IP:8080

测试电脑是否能访问：

text 复制代码

http://测试服务器IP:8080/captchaImage

后端服务是否启动。
服务器防火墙或安全组是否放开 8080。
后端是否允许当前桌面端访问接口。

14. 当前方案边界

当前安装包方案包含：

Windows 桌面客户端。
Electron 运行壳。
若依 Vue 前端静态资源。
本地保存后端 API 地址的能力。

当前安装包方案不包含：

Java 后端。
MySQL 或 MariaDB。
Redis。
OCR、模型、算法服务。
自动更新。
代码签名证书。

后端仍需要单独部署到测试服务器或一体机。

15. 后续优化建议

建议后续按优先级优化：

配置正式应用图标，替换 Electron 默认图标。
增加代码签名，减少 Windows 安全提示。
增加安装包版本号和构建日期展示。
增加内网下载页，统一分发安装包。
增加自动更新能力，但需要先明确客户现场网络策略。
增加安装包哈希校验，方便确认安装包未损坏或被替换。

16. 技术博客提纲

后续可将本文改写为技术博客，标题可以是：

text 复制代码

如何把若依 Vue 管理后台包装成 Windows 桌面安装包

建议博客结构：

背景：为什么 B 端后台不再只通过浏览器访问。
目标：安装后桌面打开，不依赖用户手动打开浏览器。
技术选型：Electron + Vue + electron-builder。
改造步骤：添加 Electron 主进程和 preload。
API 地址处理：首次启动填写后端地址并本地保存。
打包配置：NSIS 用户级安装包配置。
构建命令和产物归档。
测试流程：安装、启动、连接后端、登录、卸载。
踩坑记录：npm.ps1、GitHub 下载超时、未知发布者。
总结：这种方式适合一体机、局域网和客户现场测试交付。

17. 快速命令汇总

进入前端工程：

powershell 复制代码

cd C:\Users\WD\Desktop\test-project\test-project\Project\web\RuoYi-Vue3

构建 Windows 安装包：

powershell 复制代码

npm.cmd run build:installer

安装包输出位置：

text 复制代码

C:\Users\WD\Desktop\test-project\test-project\Project\deploy\packages\Appliance Desktop Setup-YYYYMMDD.exe

验证后端：

text 复制代码

http://测试服务器IP:8080/captchaImage

测试账号：

text 复制代码

admin / admin123

效果视频：