本文引用的文件
本文面向使用 ai-electron 子项目的开发者,系统说明 Electron 桌面客户端的本地开发、前端构建、Electron 主进程构建、安装包打包、加密、测试以及自动更新依赖。文档重点解释 ai-electron/package.json 中的脚本如何协作,并给出新增平台、调整打包产物和接入更新服务器的实操指引。
ai-electron 是一个基于 ElectronEgg(ee-core / ee-bin)封装的桌面客户端工程,整体由三部分组成:
ai-electron/frontend,由 Vite 构建后输出到 frontend/dist。ai-electron/electron,通过 ee-bin 编译或复制为 public/electron,最终被 electron-builder 打包进应用。构建配置:位于 ai-electron/cmd,包含自定义命令行工具 bin.js 和多套 electron-builder 配置。
graph TB
Root["ai-electron 根目录"] --> Frontend["frontend<br/>Vite 前端工程"]
Root --> Electron["electron<br/>Electron 主进程源码"]
Root --> Public["public<br/>Electron 运行时入口与静态资源"]
Root --> Cmd["cmd<br/>ee-bin 配置与 builder 配置"]
Root --> Out["out<br/>electron-builder 产物输出目录"]
Frontend -->|npm run build| Dist["frontend/dist"]
Dist -->|ee-bin move| PublicDist["public/dist"]
Electron -->|ee-bin build| PublicElectron["public/electron"]
PublicElectron -->|electron-builder| Out
Cmd -->|ee-bin dev/build/start/encrypt| Public
Cmd -->|electron-builder| Out
图表来源
章节来源
| 脚本 | 执行内容 | 作用 |
|---|---|---|
dev |
ee-bin dev |
启动开发模式,按 cmd/bin.js 中 dev 配置启动前端与 Electron。 |
build |
npm run build-frontend && npm run build-electron && ee-bin encrypt |
标准生产构建:先构建前端,再构建 Electron,最后执行加密。 |
start |
ee-bin start |
以生产环境运行 Electron 应用。 |
dev-frontend |
ee-bin dev --serve=frontend |
仅启动前端开发服务。 |
dev-electron |
ee-bin dev --serve=electron |
仅启动 Electron 开发服务。 |
build-frontend |
ee-bin build --cmds=frontend && ee-bin move --flag=frontend_dist |
构建前端并将 frontend/dist 移动到 public/dist。 |
build-electron |
ee-bin build --cmds=electron |
编译或复制 Electron 主进程到 public/electron。 |
icon |
ee-bin icon |
调用框架提供的图标处理命令。 |
test |
vitest run |
运行主进程侧单元测试。 |
test:watch |
vitest |
监听模式下运行单测。 |
typecheck |
tsc --noEmit |
TypeScript 类型检查。 |
re-sqlite |
electron-rebuild -f -w better-sqlite3 |
重建原生模块 better-sqlite3。 |
build-w |
ee-bin build --cmds=win64 |
构建 Windows x64 NSIS 安装包。 |
build-we |
ee-bin build --cmds=win_e |
构建 Windows 便携版。 |
build-m |
ee-bin build --cmds=mac_arm64 |
构建 macOS ARM64 包。 |
build-m-x86 |
ee-bin build --cmds=mac |
构建 macOS x64 包。 |
build-m-arm64 |
ee-bin build --cmds=mac_arm64 |
构建 macOS ARM64 包,语义更明确。 |
build-l |
ee-bin build --cmds=linux |
构建 Linux deb 包。 |
章节来源
| 依赖 | 类型 | 作用 |
|---|---|---|
ee-bin |
开发依赖 | 项目级构建编排器,负责 dev、build、move、start、encrypt、icon 等命令。 |
electron |
开发依赖 | Electron 运行时,用于开发和生产启动。 |
electron-builder |
开发依赖 | 跨平台安装包打包工具,根据 cmd/builder*.json 生成 nsis、portable、deb 等产物。 |
vitest |
开发依赖 | 主进程侧单元测试运行器,由 vitest.config.mts 限定只跑 electron/**/*.test.ts。 |
@electron/rebuild |
开发依赖 | 配合 re-sqlite 脚本重建 native 模块。 |
electron-updater |
运行时依赖 | 提供客户端自动更新能力,但当前仓库未在主进程中直接引入其 API。 |
章节来源
npm run build 是完整的生产构建入口,顺序如下:
build-frontend:
ee-bin build --cmds=frontend,进入 frontend 目录执行 npm run build。ee-bin move --flag=frontend_dist,将 frontend/dist 移动到 public/dist。build-electron:
ee-bin build --cmds=electron,将 electron 源码编译或复制到 public/electron。执行 ee-bin encrypt:
public/dist 前端资源进行混淆。对 public/electron 主进程代码进行混淆,并保留指定入口文件。
flowchart TD
Start["开始:npm run build"] --> BuildFrontend["构建前端:ee-bin build --cmds=frontend"]
BuildFrontend --> MoveFrontend["移动前端产物:ee-bin move --flag=frontend_dist"]
MoveFrontend --> BuildElectron["构建 Electron:ee-bin build --cmds=electron"]
BuildElectron --> Encrypt["执行加密:ee-bin encrypt"]
Encrypt --> End["结束:可执行打包命令"]
图表来源
frontend。ee-bin 触发 npm run build。frontend/dist → public/dist。public/dist/**/*.(js|json),采用混淆策略,清理原目录后再写入。electron。public/electron。electron/ 下部分目录原样复制到 public/electron。public/electron/**/*.(js|json),特别保留 main.js 和 preload/bridge.js。章节来源
| 命令 | 平台 | 目标 | 说明 |
|---|---|---|---|
build-w |
Windows | win64 | 使用 builder.json,打包为 NSIS 安装包,x64。 |
build-we |
Windows | win_e | 使用 builder.json,打包为 portable 便携版,x64。 |
build-m |
macOS | mac_arm64 | 使用 builder-mac-arm64.json,ARM64 架构。 |
build-m-x86 |
macOS | mac | 使用 builder-mac.json,x64 架构。 |
build-m-arm64 |
macOS | mac_arm64 | 与 build-m 相同,语义更清晰。 |
build-l |
Linux | linux | 使用 builder-linux.json,打包为 deb,x64。 |
builder.json:通用基础配置,定义产品名称、应用 ID、版权、输出目录 out、asar 打包、语言、排除目录、NSIS 安装器选项、Windows/Linux 默认 target。builder-linux.json:Linux 专用配置,指定 deb 目标及分类。builder-mac.json:macOS x64 配置,启用深色模式支持,关闭 hardenedRuntime。builder-mac-arm64.json:macOS ARM64 配置,结构与 x64 基本一致。
flowchart LR
Win64["win64<br/>NSIS 安装包"] --> BuilderJson["builder.json"]
WinPortable["win_e<br/>便携版"] --> BuilderJson
MacArm["mac_arm64<br/>macOS ARM64"] --> BuilderMacArm["builder-mac-arm64.json"]
MacX64["mac<br/>macOS x64"] --> BuilderMac["builder-mac.json"]
LinuxDeb["linux<br/>deb"] --> BuilderLinux["builder-linux.json"]
图表来源
章节来源
package.json 已声明 electron-updater 依赖,说明项目具备接入自动更新的依赖基础。但该依赖目前并未在 electron/main.ts 或其他可见 Electron 主进程文件中被直接 import 或使用。
flowchart TD
PackageJson["package.json<br/>dependencies.electron-updater"] --> UpdateLibrary["electron-updater 库"]
MainTs["electron/main.ts<br/>ElectronEgg 启动"] --> AppRun["app.run()"]
UpdateLibrary -.-> MainTs
Note["当前仓库未在主进程中发现 autoUpdater 初始化逻辑"]
图表来源
builder.json 中 publish 配置为 generic provider,url 为空字符串,表示未配置发布服务器。electron-updater,也需要同时配置有效的 update server URL。章节来源
英文 README 与中文 README 均指向外部教程链接:
这意味着本项目自身 README 没有内联具体安装步骤,而是复用 ElectronEgg 的安装说明。
章节来源
仓库提供了跨平台卸载脚本:
cmd/uninstall.batcmd/uninstall.sh它们会尝试终止应用进程并删除用户数据目录,例如:
%APPDATA%\QingJian、%APPDATA%\qingjian-client。$HOME/.config/qingjian-client、$HOME/.local/share/QingJian、$HOME/.qingjian-client。注意:这些脚本属于“清理用户数据”的工具,不是 Windows 卸载程序本身;实际安装包卸载逻辑由 electron-builder 生成的 NSIS 安装器处理。
章节来源
在当前仓库快照中,未发现名为 regInfo.exe 的文件,也未发现主进程或构建脚本中对 regInfo.exe 的直接引用。README 中也没有明确说明该工具的用法。因此:
regInfo.exe 是由其他工具链、第三方组件或后续版本生成的辅助工具,则不应将其视为本仓库当前稳定实现的一部分。electron/main.ts,并在合适的生命周期中接入业务逻辑。章节来源
假设需要新增一个 Windows ARM64 构建目标:
cmd/bin.js 的 build 对象中新增对应任务,例如命名为 win_arm64,指向 electron-builder 并使用 Windows 配置。ai-electron/package.json 的 scripts 中新增命令,例如 build-wa,调用 ee-bin build --cmds=win_arm64。cmd/bin.js 的 build 配置中添加独立 cmd 任务。参考已有结构:
win64、win_e、mac、mac_arm64、linux 均通过 ee-bin build --cmds=<task> 调用。章节来源
要修改 electron-builder 产物,应优先编辑 cmd/builder*.json:
productName、appId、copyright。directories.output 调整输出目录。files 控制哪些文件进入应用包。extraResources 控制附加资源。nsis 配置 Windows 安装包行为。publish 配置自动更新发布地址。注意:builder.json 是 Windows/Linux 默认配置,macOS 分别使用 builder-mac.json 和 builder-mac-arm64.json。
章节来源
由于当前主进程未直接使用 electron-updater,接入更新需要补充主进程逻辑:
electron-updater。autoUpdater,设置 update server URL。builder.json 的 publish 中填写真实 update server 地址。electron-updater 规范的更新元数据。当前仓库中可直接参考的配置点:
electron-updater 依赖已在 package.json 中声明。builder.json 中已有 publish 字段,但 url 为空。章节来源
graph TB
Pkg["ai-electron/package.json"] --> EEBin["ee-bin"]
Pkg --> Electron["electron"]
Pkg --> EB["electron-builder"]
Pkg --> Vitest["vitest"]
Pkg --> Rebuild["@electron/rebuild"]
Pkg --> Updater["electron-updater"]
EEBin --> DevBuild["dev/build/move/start/encrypt"]
EB --> BuilderCfg["cmd/builder*.json"]
Vitest --> TestConfig["vitest.config.mts"]
Rebuild --> Sqlite["better-sqlite3 原生模块重建"]
图表来源
章节来源
ee-bin 的 electron 构建配置开启 minify。cmd/bin.js 注释调整为 inline 或 external。electron/**/*.test.ts,避免误跑前端测试。章节来源
常见原因:
cmd/bin.js 中 dev.frontend.port 不一致。frontend/dist 未被正确移动到 public/dist。建议排查:
npm run build-frontend 确认前端构建是否成功。cmd/bin.js 中 move.frontend_dist 的源路径和目标路径。frontend 子工程的构建日志。章节来源
典型场景:
better-sqlite3 预编译二进制不匹配。建议排查:
npm run re-sqlite 重新编译 better-sqlite3。@electron/rebuild。章节来源
现象:
可能原因:
build/icons/icon.ico 或 build/icons/icon.png、build/icons/icon.icns 不存在。建议排查:
cmd/builder.json 中 Windows 图标路径。cmd/builder-linux.json 中 Linux 图标路径。.icns 图标路径。npm run icon 调用框架图标命令生成或校验图标。章节来源
现象:
可能原因:
建议排查:
hardenedRuntime、签名证书、开发者账号权限。章节来源
现象:
可能原因:
builder.json 中 publish.url 为空或未配置。electron-updater。建议排查:
builder.json 中配置有效的 generic update server URL。electron-updater。章节来源
ai-electron 的构建体系以 package.json 脚本为入口,以 ee-bin 为编排核心,以 electron-builder 为打包后端。标准构建流程严格遵循“前端构建 → Electron 构建 → 加密”的顺序;平台构建通过 cmd/bin.js 中的任务映射到不同 builder*.json 配置。自动更新依赖已就绪,但当前仓库未在主进程中直接集成 electron-updater,也未配置有效更新服务器。新增平台和调整产物时应优先修改 cmd/bin.js 和 cmd/builder*.json,并在必要时补充主进程更新逻辑。