企业官网建设流程全解析

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

1. 文档目的

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

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

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

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

2. 方案背景

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

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

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

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

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

3. 最终使用方式

后端部署方式保持不变：

Java 后端 + MySQL/MariaDB + Redis

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

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

桌面端交付方式变为：

Appliance Desktop Setup-YYYYMMDD.exe

测试人员操作：

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

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

5. 使用测试账号登录：

admin / admin123

注意：

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

4. 技术架构

整体结构如下：

Windows 桌面应用 └─ Electron 主进程 └─ BrowserWindow └─ 若依 Vue 前端 dist └─ Axios 请求一体机后端 API 测试服务器 / 一体机 ├─ Java 后端 ├─ MySQL 或 MariaDB └─ Redis

关键点：

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

5. 项目目录

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

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

前端工程目录：

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

安装包输出目录：

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

6. Electron 入口

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

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中，关键脚本如下：

{"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"}}

推荐日常打安装包使用：

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：

{"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. 安装包归档脚本

脚本位置：

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

作用：

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

Appliance Desktop Setup-YYYYMMDD.exe

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

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

10. 打包流程

进入前端工程目录：

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

执行安装包构建：

npm.cmd run build:installer

成功后应看到类似输出：

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

最终交付文件：

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

11. 分发给同事测试

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

Appliance Desktop Setup-YYYYMMDD.exe

可以通过以下方式分发：

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

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

测试客户端安装方式： 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 后端连通性测试

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

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

如果不能访问，先检查：

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

12.2 安装测试

测试步骤：

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

验收标准：

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

12.3 启动测试

测试步骤：

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

验收标准：

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

12.4 登录测试

测试账号：

admin / admin123

验收标准：

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

12.5 卸载测试

测试步骤：

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

验收标准：

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

本项目当前测试结果：

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

13. 常见问题

13.1 npm 命令被 PowerShell 拦截

现象：

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

处理方式：

使用：

npm.cmd run build:installer

不要直接使用：

npm run build:installer

13.2 electron-builder 下载超时

现象：

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 管理。

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

npm.cmd run build:installer

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

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

pnpm install pnpm run build:installer

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

13.4 Windows 提示未知发布者

原因：

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

测试阶段处理方式：

更多信息 -> 仍要运行

正式客户交付建议：

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

13.5 安装后连接不上后端

优先检查：

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

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

2. 测试电脑是否能访问：

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

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

14. 当前方案边界

当前安装包方案包含：

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

当前安装包方案不包含：

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

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

15. 后续优化建议

建议后续按优先级优化：

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

16. 技术博客提纲

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

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

建议博客结构：

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

17. 快速命令汇总

进入前端工程：

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

构建 Windows 安装包：

npm.cmd run build:installer

安装包输出位置：

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

验证后端：

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

测试账号：

admin / admin123

效果视频：