Electron 桌面端打包流程说明

本文档说明本仓库（Vue 3 + Vite + Vue Router History 模式）如何开发与打包为 Windows 桌面应用。

1. 架构概要

环节	说明
渲染进程	Vite 构建的前端 SPA，逻辑与浏览器中一致
主进程	`electron/main.js`，负责创建窗口与加载页面
开发环境	Electron 窗口加载 Vite 开发服务器：`http://127.0.0.1:5176`（与 `npm run dev` 一致）
生产环境	主进程在 `127.0.0.1` 上启动本地 HTTP 静态服务（`sirv`，`single: true`），再 `loadURL`，以支持 History 路由（避免仅用 `file://` 导致子路径异常）
打包工具	electron-builder ，Windows 目标为 NSIS 安装包

2. 环境要求

Node.js ：与 package.json 中 engines 一致（建议 ^20.19.0 或 >=22.12.0）
操作系统 ：开发/打包可在 Windows 上进行；electron-builder 当前配置为生成 Windows（win.nsis） 产物

首次安装需能访问 npm registry；安装 Electron 时会下载对应平台二进制，若访问 GitHub 不稳定，需配置代理或使用国内镜像（见下文「常见问题」）。

3. 安装依赖

在项目根目录执行：

bash 复制代码

npm install

安装完成后应存在：electron、electron-builder、sirv 等依赖。

4. 开发调试（Electron + Vite 热更新）

bash 复制代码

npm run electron:dev

行为简述：

通过 concurrently 同时启动：npm run dev（Vite，0.0.0.0:5176）与 wait-on 等待端口就绪后的 electron .
设置环境变量 ELECTRON_USE_VITE=1，主进程识别为开发模式，不起本地静态服务，直接打开 http://127.0.0.1:5176
可在此阶段验证路由、接口、WebSocket 等

5. 仅前端构建（不启动 Electron）

类型检查 + Vite 产出静态资源至 dist/：

bash 复制代码

npm run build

6. 打包前试跑（未生成安装包）

先完成前端构建，再生成 未封装 的应用目录（便于快速验证生产加载方式）：

bash 复制代码

npm run electron:pack

等价于：npm run build → electron-builder --dir。

产物位置： release/ 目录下（具体子目录名随版本与平台略有不同），进入其中运行可执行文件，确认 本地 HTTP + History 是否正常。

7. 正式打包 Windows 安装程序

bash 复制代码

npm run electron:build

流程： npm run build（生成 dist/）→ electron-builder 打 Windows NSIS 安装包。

产物位置： 默认在 release/ （由 package.json 中 build.directories.output 指定）。

安装后在目标机器上完整走一遍：启动、主要页面、网络功能、退出。

8. 配置项速查（本仓库）

配置项	位置	说明
主进程入口	`package.json` → `main`	`electron/main.js`
应用标识	`build.appId`	如 `com.screen.client`
显示名称	`build.productName`	如 `Screen Client`
打包输出目录	`build.directories.output`	`release`
打入安装包的文件	`build.files`	含 `dist/*/`、`electron/*/`、`package.json`；生产依赖由 electron-builder 按 `dependencies` 处理
Windows 目标	`build.win.target`	`nsis`（安装程序）

修改 应用名、图标、版本号 时，主要改 package.json 的 version、build 段及（如需）build.win.icon 等字段，详见 electron-builder 文档。

9. 流程简图

复制代码

开发:  npm run electron:dev
         → Vite :5176 + Electron 加载 http://127.0.0.1:5176

发布:  npm run electron:build
         → vite build → dist/
         → electron-builder → release/ 下 NSIS 安装包
         → 用户安装后：主进程对 dist 起本机 HTTP → loadURL（History 可用）

10. 常见问题

Electron 安装失败 / 下载超时

检查网络与代理；或在安装前设置国内镜像，例如（示例，以实际镜像地址为准）：
bash 复制代码
```
set ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
npm install
```

（PowerShell 中可使用 $env:ELECTRON_MIRROR="..."。）

打包后白屏或路由 404

确认已执行 vite build 且 dist 被打进包内
History 模式依赖主进程的 本地静态服务 ；不要改为仅用 file:// 打开 index.html 而不做 SPA 回退

安装包体积较大

属正常现象：内含 Chromium 与 Electron 运行时；可按需使用 asar、按需剔除不必要文件等（进阶，需对照 electron-builder 文档）

11. 可选后续工作

代码签名 ：减轻 Windows SmartScreen 提示（需证书与 build.win 签名相关配置）
自动更新 ：如 electron-updater + 更新服务器
多平台 ：在 build 中增加 mac、linux 等目标（需在对应系统或使用 CI 构建）

文档版本与仓库脚本保持一致；若修改 package.json 脚本或 electron/main.js，请同步更新本文档。