3 步把 RuoYi-Vue3 搬上桌面：Electron 跨平台桌面应用改造实战
【免费下载链接】RuoYi-Vue3:tada: (RuoYi)官方仓库 基于SpringBoot，Spring Security，JWT，Vue3 & Vite、Element Plus 的前后端分离权限管理系统项目地址: https://gitcode.com/GitHub_Trending/ruo/RuoYi-Vue3
RuoYi-Vue3 是一套基于 Vue3 + Vite + Element Plus 的权限管理系统。放到内网部署后，业务方经常提"要个应用图标"、要系统托盘常驻、要文件直接拖进窗口上传这类需求。这篇文章就用 Electron 把这个现成的 Vue3 项目改造成 Windows / macOS / Linux 跨平台桌面应用：加两个文件、补两个脚本，业务代码一行不动。
01 为什么要把 Web 后台搬进桌面
这节回答一个问题：已经在跑的 Web 后台，套一层桌面壳到底图什么。
真实项目里踩过的三类痛点：
- 业务方要"一个应用"。内网里后台靠书签 + 标签页访问，容易丢、容易误关，桌面图标加开机入口更符合企业软件的使用习惯。
- 数据不出办公网。合规要求后台不上公网，终端又常被统一管理、浏览器功能被裁剪。桌面形态方便统一管控安装、卸载和授权，例如车间、财务这类部门的终端往往只保留内网白名单。
- Web 做不了桌面独有的事。托盘常驻、全局快捷键唤起窗口、本地文件直接拖进上传区，这三样浏览器都提供不了。
选 Electron 而不是 PWA 或 Tauri，理由很直接：项目本身就是 Vue3 技术栈，Electron 同为 JS 生态，学习成本几乎为零；PWA 摸不到系统托盘和全局快捷键；Tauri 包体更小，但 Rust 工具链的入门成本高，打包和自动更新生态的成熟度也差半档。再加上 Electron 的调试工具就是熟悉的 DevTools，排错体验和 Web 端完全一致。
| 能力 | Web 后台 | Electron 桌面应用 |
|---|---|---|
| 内网驻留形态 | 书签 + 标签页 | 图标、托盘、全局快捷键 |
| 本地文件交互 | 受沙箱限制 | 直接拖进窗口 |
| 系统集成 | 无 | 托盘、菜单、通知 |
| 分发形态 | URL | 各平台安装包 |
02 桌面化路线图：Vue3 工程到安装包的 4 层
这节先把改造路径摆清楚，避免"改一处跑一处"的混乱。
每一层的分工：主进程负责建窗口、按开发/生产双模式加载资源、管理托盘菜单；preload 脚本是两个世界之间唯一的通道，页面能调到的只有它暴露的函数；渲染进程侧的登录、权限菜单、动态路由逻辑与 Web 版完全一致。也就是说，桌面化的成本全部集中在"壳"这一层，业务层零改动。
03 三步落地
这节给出最小可用文件集与配置，按"主进程 → 安全桥 → 脚本"三步走。
3.1 Electron 主进程怎么配
这一步解决窗口创建与双模式加载，同时把安全默认值钉死。新建 electron/main.cjs 作为主进程入口：渲染进程不允许碰 Node API，contextIsolation: true和nodeIntegration: false直接从窗口参数里写死；加载分两种模式——开发指向本地 vite 端口，生产直接读 dist。再注意一个细节：本项目 package.json 里"type": "module"，所以入口文件命名main.cjs，require才能正常用。
// electron/main.cjs const { app, BrowserWindow } = require('electron') const path = require('path') function createWindow() { const win = new BrowserWindow({ width: 1280, height: 800, webPreferences: { preload: path.join(__dirname, 'preload.js'), contextIsolation: true, nodeIntegration: false } }) app.isPackaged ? win.loadFile(path.join(__dirname, '../dist/index.html')) : win.loadURL('http://localhost:80') } app.whenReady().then(createWindow)验证：跑起 electron 后打开 DevTools，登录页应正常加载，Console 里window.electronAPI不再是 undefined。主进程再补两个常规行为即可：非 macOS 下所有窗口关闭即退出，macOS 激活事件里重建窗口。
3.2 preload 安全桥写法
【免费下载链接】RuoYi-Vue3:tada: (RuoYi)官方仓库 基于SpringBoot，Spring Security，JWT，Vue3 & Vite、Element Plus 的前后端分离权限管理系统项目地址: https://gitcode.com/GitHub_Trending/ruo/RuoYi-Vue3
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
