构建、打包与自动更新.md 22 KB

构建、打包与自动更新

本文引用的文件

  • ai-electron/package.json
  • ai-electron/cmd/bin.js
  • ai-electron/cmd/builder.json
  • ai-electron/cmd/builder-linux.json
  • ai-electron/cmd/builder-mac.json
  • ai-electron/cmd/builder-mac-arm64.json
  • ai-electron/electron/main.ts
  • ai-electron/vitest.config.mts
  • ai-electron/tsconfig.json
  • ai-electron/README.md
  • ai-electron/README.zh-CN.md
  • cmd/uninstall.bat
  • cmd/uninstall.sh

目录

  1. 引言
  2. 项目结构
  3. 核心命令与依赖说明
  4. 构建与打包总流程
  5. 平台构建目标差异
  6. 自动更新机制
  7. 安装、卸载与注册激活相关说明
  8. 扩展指南:新增平台、修改产物、接入更新服务器
  9. 依赖关系分析
  10. 性能与工程化注意事项
  11. 常见问题排查
  12. 结论

引言

本文面向使用 ai-electron 子项目的开发者,系统说明 Electron 桌面客户端的本地开发、前端构建、Electron 主进程构建、安装包打包、加密、测试以及自动更新依赖。文档重点解释 ai-electron/package.json 中的脚本如何协作,并给出新增平台、调整打包产物和接入更新服务器的实操指引。

项目结构

ai-electron 是一个基于 ElectronEgg(ee-core / ee-bin)封装的桌面客户端工程,整体由三部分组成:

  • 前端资源:位于 ai-electron/frontend,由 Vite 构建后输出到 frontend/dist。
  • Electron 主进程:位于 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
    

图表来源

  • ai-electron/cmd/bin.js:1-270
  • ai-electron/cmd/builder.json:1-57
  • ai-electron/electron/main.ts:1-19

章节来源

  • ai-electron/cmd/bin.js:1-270
  • ai-electron/cmd/builder.json:1-57
  • ai-electron/electron/main.ts:1-19

核心命令与依赖说明

package.json scripts 总览

脚本 执行内容 作用
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 包。

章节来源

  • ai-electron/package.json:1-42

关键依赖说明

依赖 类型 作用
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。

章节来源

  • ai-electron/package.json:25-42
  • ai-electron/vitest.config.mts:1-10

构建与打包总流程

标准构建流程

npm run build 是完整的生产构建入口,顺序如下:

  1. 执行 build-frontend:
    • 调用 ee-bin build --cmds=frontend,进入 frontend 目录执行 npm run build。
    • 调用 ee-bin move --flag=frontend_dist,将 frontend/dist 移动到 public/dist。
  2. 执行 build-electron:
    • 调用 ee-bin build --cmds=electron,将 electron 源码编译或复制到 public/electron。
  3. 执行 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["结束:可执行打包命令"]
      

图表来源

  • ai-electron/package.json:5-12
  • ai-electron/cmd/bin.js:17-199
  • ai-electron/cmd/bin.js:201-254

前端构建细节

  • 前端目录:frontend。
  • 构建命令:由 ee-bin 触发 npm run build。
  • 产物移动:frontend/dist → public/dist。
  • 加密范围:public/dist/**/*.(js|json),采用混淆策略,清理原目录后再写入。

Electron 构建细节

  • 源码目录:electron。
  • 默认构建方式:bundle,使用 esbuild 将主进程打包成 public/electron。
  • 输出格式:CommonJS,便于 Electron 主进程加载。
  • 额外复制:支持将 electron/ 下部分目录原样复制到 public/electron。
  • 加密范围:public/electron/**/*.(js|json),特别保留 main.js 和 preload/bridge.js。

章节来源

  • ai-electron/package.json:5-18
  • ai-electron/cmd/bin.js:17-199
  • ai-electron/cmd/bin.js:201-254

平台构建目标差异

平台命令对照

命令 平台 目标 说明
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"]
    

图表来源

  • ai-electron/cmd/bin.js:60-108
  • ai-electron/cmd/builder.json:1-57
  • ai-electron/cmd/builder-linux.json:1-41
  • ai-electron/cmd/builder-mac.json:1-34
  • ai-electron/cmd/builder-mac-arm64.json:1-34

章节来源

  • ai-electron/cmd/bin.js:60-108
  • ai-electron/cmd/builder.json:1-57
  • ai-electron/cmd/builder-linux.json:1-41
  • ai-electron/cmd/builder-mac.json:1-34
  • ai-electron/cmd/builder-mac-arm64.json:1-34

自动更新机制

依赖现状

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 初始化逻辑"]

图表来源

  • ai-electron/package.json:40-42
  • ai-electron/electron/main.ts:1-19

实际行为

  • 当前 builder.json 中 publish 配置为 generic provider,url 为空字符串,表示未配置发布服务器。
  • 即使未来在主进程中集成 electron-updater,也需要同时配置有效的 update server URL。

章节来源

  • ai-electron/package.json:40-42
  • ai-electron/cmd/builder.json:28-38
  • ai-electron/electron/main.ts:1-19

安装、卸载与注册激活相关说明

README 中的安装说明

英文 README 与中文 README 均指向外部教程链接:

  • 英文 README:安装指南链接为 ElectronEgg 官方文档。
  • 中文 README:安装文档链接同样指向 ElectronEgg 官方文档。

这意味着本项目自身 README 没有内联具体安装步骤,而是复用 ElectronEgg 的安装说明。

章节来源

  • ai-electron/README.md:93-98
  • ai-electron/README.zh-CN.md:93-98

卸载说明

仓库提供了跨平台卸载脚本:

  • Windows:cmd/uninstall.bat
  • Linux:cmd/uninstall.sh

它们会尝试终止应用进程并删除用户数据目录,例如:

  • Windows:%APPDATA%\QingJian、%APPDATA%\qingjian-client。
  • Linux:$HOME/.config/qingjian-client、$HOME/.local/share/QingJian、$HOME/.qingjian-client。

注意:这些脚本属于“清理用户数据”的工具,不是 Windows 卸载程序本身;实际安装包卸载逻辑由 electron-builder 生成的 NSIS 安装器处理。

章节来源

  • cmd/uninstall.bat:1-58
  • cmd/uninstall.sh:1-53
  • ai-electron/cmd/builder.json:20-31

关于 regInfo.exe 与激活命令

在当前仓库快照中,未发现名为 regInfo.exe 的文件,也未发现主进程或构建脚本中对 regInfo.exe 的直接引用。README 中也没有明确说明该工具的用法。因此:

  • 如果 regInfo.exe 是由其他工具链、第三方组件或后续版本生成的辅助工具,则不应将其视为本仓库当前稳定实现的一部分。
  • 若需要在客户端中增加注册信息校验或激活流程,应参考现有 Electron 主进程入口 electron/main.ts,并在合适的生命周期中接入业务逻辑。

章节来源

  • ai-electron/electron/main.ts:1-19

扩展指南:新增平台、修改产物、接入更新服务器

新增平台构建脚本示例

假设需要新增一个 Windows ARM64 构建目标:

  1. 在 cmd/bin.js 的 build 对象中新增对应任务,例如命名为 win_arm64,指向 electron-builder 并使用 Windows 配置。
  2. 在 ai-electron/package.json 的 scripts 中新增命令,例如 build-wa,调用 ee-bin build --cmds=win_arm64。
  3. 如平台有特殊产物要求,可在 cmd/bin.js 的 build 配置中添加独立 cmd 任务。

参考已有结构:

  • win64、win_e、mac、mac_arm64、linux 均通过 ee-bin build --cmds=<task> 调用。

章节来源

  • ai-electron/cmd/bin.js:60-108
  • ai-electron/package.json:15-18

修改打包产物示例

要修改 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。

章节来源

  • ai-electron/cmd/builder.json:1-57
  • ai-electron/cmd/builder-linux.json:1-41
  • ai-electron/cmd/builder-mac.json:1-34
  • ai-electron/cmd/builder-mac-arm64.json:1-34

接入更新服务器示例

由于当前主进程未直接使用 electron-updater,接入更新需要补充主进程逻辑:

  1. 在 Electron 主进程入口中引入 electron-updater。
  2. 配置 autoUpdater,设置 update server URL。
  3. 在应用启动或用户主动检查更新时调用检查更新方法。
  4. 在 builder.json 的 publish 中填写真实 update server 地址。
  5. 确保服务端返回符合 electron-updater 规范的更新元数据。

当前仓库中可直接参考的配置点:

  • electron-updater 依赖已在 package.json 中声明。
  • builder.json 中已有 publish 字段,但 url 为空。

章节来源

  • ai-electron/package.json:40-42
  • ai-electron/cmd/builder.json:28-38

依赖关系分析

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 原生模块重建"]

图表来源

  • ai-electron/package.json:13-42
  • ai-electron/cmd/bin.js:1-270
  • ai-electron/vitest.config.mts:1-10

章节来源

  • ai-electron/package.json:13-42
  • ai-electron/cmd/bin.js:1-270
  • ai-electron/vitest.config.mts:1-10

性能与工程化注意事项

  • 前端构建与 Electron 构建分离,有利于缓存增量构建结果。
  • 生产构建默认不压缩主进程代码,可通过 ee-bin 的 electron 构建配置开启 minify。
  • Source map 默认关闭;如需调试,可按 cmd/bin.js 注释调整为 inline 或 external。
  • asar 打包默认开启,有助于保护应用代码和资源。
  • 单元测试只包含主进程侧 electron/**/*.test.ts,避免误跑前端测试。

章节来源

  • ai-electron/cmd/bin.js:17-199
  • ai-electron/vitest.config.mts:1-10
  • ai-electron/cmd/builder.json:1-27

常见问题排查

前端构建失败

常见原因:

  • 前端依赖未安装或版本冲突。
  • Vite 端口与 cmd/bin.js 中 dev.frontend.port 不一致。
  • frontend/dist 未被正确移动到 public/dist。

建议排查:

  • 单独执行 npm run build-frontend 确认前端构建是否成功。
  • 检查 cmd/bin.js 中 move.frontend_dist 的源路径和目标路径。
  • 查看 frontend 子工程的构建日志。

章节来源

  • ai-electron/package.json:9-11
  • ai-electron/cmd/bin.js:8-16
  • ai-electron/cmd/bin.js:126-144

Electron 原生模块编译失败

典型场景:

  • 本机 Node/Electron 版本与 better-sqlite3 预编译二进制不匹配。
  • 缺少 C++ 编译工具链。

建议排查:

  • 执行 npm run re-sqlite 重新编译 better-sqlite3。
  • 确保已安装 @electron/rebuild。
  • 如仍失败,检查 Node.js、Python、Visual Studio 或 Xcode 工具链。

章节来源

  • ai-electron/package.json:14-14
  • ai-electron/package.json:25-30

图标缺失

现象:

  • 安装包图标、快捷方式图标、窗口图标不正确或缺失。

可能原因:

  • build/icons/icon.ico 或 build/icons/icon.png、build/icons/icon.icns 不存在。
  • 不同平台使用了不同的图标文件名。

建议排查:

  • 检查 cmd/builder.json 中 Windows 图标路径。
  • 检查 cmd/builder-linux.json 中 Linux 图标路径。
  • 检查 macOS 配置中的 .icns 图标路径。
  • 使用 npm run icon 调用框架图标命令生成或校验图标。

章节来源

  • ai-electron/cmd/builder.json:20-31
  • ai-electron/cmd/builder-linux.json:25-35
  • ai-electron/cmd/builder-mac.json:24-32
  • ai-electron/cmd/builder-mac-arm64.json:24-32
  • ai-electron/package.json:13-13

安装包签名失败

现象:

  • Windows NSIS 安装包或 macOS 应用签名失败。

可能原因:

  • 缺少证书或环境变量。
  • macOS hardenedRuntime 配置与证书不匹配。
  • 非签名环境却启用了强制签名。

建议排查:

  • Windows:检查签名证书路径、密码和代码签名工具。
  • macOS:检查 hardenedRuntime、签名证书、开发者账号权限。
  • Linux:通常不涉及传统签名,主要关注 deb 包元数据。

章节来源

  • ai-electron/cmd/builder.json:20-31
  • ai-electron/cmd/builder-mac.json:24-34
  • ai-electron/cmd/builder-mac-arm64.json:24-34

自动更新服务器不可达

现象:

  • 客户端无法检测到新版本。
  • 更新下载失败。

可能原因:

  • builder.json 中 publish.url 为空或未配置。
  • 主进程未初始化 electron-updater。
  • 更新服务器未返回正确的版本元数据。

建议排查:

  • 先在 builder.json 中配置有效的 generic update server URL。
  • 在主进程中引入并初始化 electron-updater。
  • 验证更新服务器返回 latest.yml 或等效元数据。
  • 检查网络访问、代理、SSL 证书和跨域限制。

章节来源

  • ai-electron/cmd/builder.json:28-38
  • ai-electron/package.json:40-42

结论

ai-electron 的构建体系以 package.json 脚本为入口,以 ee-bin 为编排核心,以 electron-builder 为打包后端。标准构建流程严格遵循“前端构建 → Electron 构建 → 加密”的顺序;平台构建通过 cmd/bin.js 中的任务映射到不同 builder*.json 配置。自动更新依赖已就绪,但当前仓库未在主进程中直接集成 electron-updater,也未配置有效更新服务器。新增平台和调整产物时应优先修改 cmd/bin.js 和 cmd/builder*.json,并在必要时补充主进程更新逻辑。