# Electron 客户端构建与发布 **本文引用的文件** - [ai-electron/package.json](file://ai-electron/package.json) - [ai-electron/README.md](file://ai-electron/README.md) - [ai-electron/README.zh-CN.md](file://ai-electron/README.zh-CN.md) - [ai-electron/electron/main.ts](file://ai-electron/electron/main.ts) - [ai-electron/electron/preload/lifecycle.ts](file://ai-electron/electron/preload/lifecycle.ts) - [ai-electron/electron/config/config.default.ts](file://ai-electron/electron/config/config.default.ts) - [ai-electron/electron/config/config.prod.ts](file://ai-electron/electron/config/config.prod.ts) - [ai-electron/electron/config/windowOptions.ts](file://ai-electron/electron/config/windowOptions.ts) - [ai-electron/cmd/builder.json](file://ai-electron/cmd/builder.json) - [ai-electron/cmd/builder-linux.json](file://ai-electron/cmd/builder-linux.json) - [ai-electron/cmd/builder-mac.json](file://ai-electron/cmd/builder-mac.json) - [ai-electron/cmd/builder-mac-arm64.json](file://ai-electron/cmd/builder-mac-arm64.json) - [ai-electron/frontend/bin/build.sh](file://ai-electron/frontend/bin/build.sh) - [ai-electron/frontend/bin/install.sh](file://ai-electron/frontend/bin/install.sh) - [ai-electron/frontend/bin/startup.sh](file://ai-electron/frontend/bin/startup.sh) - [ai-electron/frontend/bin/install.bat](file://ai-electron/frontend/bin/install.bat) - [ai-electron/frontend/bin/build.bat](file://ai-electron/frontend/bin/build.bat) - [ai-electron/frontend/bin/startup.bat](file://ai-electron/frontend/bin/startup.bat) ## 目录 1. [简介](#简介) 2. [项目结构总览](#项目结构总览) 3. [构建脚本总览](#构建脚本总览) 4. [前端构建流程](#前端构建流程) 5. [Electron 打包流程](#electron-打包流程) 6. [三端产物差异](#三端产物差异) 7. [自动更新与版本号管理](#自动更新与版本号管理) 8. [本地与 CI 发布指南](#本地与-ci-发布指南) 9. [常见问题排查](#常见问题排查) 10. [最佳实践与建议](#最佳实践与建议) ## 简介 本仓库中的 `ai-electron` 是一个基于 ElectronEgg(ee-core、ee-bin)和 Electron 的桌面客户端工程。它同时包含: - **前端工程**:位于 `ai-electron/frontend`,使用 pnpm/Vite 构建。 - **Electron 主进程**:位于 `ai-electron/electron`,入口为 TypeScript,最终由 ee-core/ElectronEgg 启动。 - **打包配置**:位于 `ai-electron/cmd`,由 electron-builder 消费,生成 Windows、macOS、Linux 安装包。 - **依赖说明**:在 `ai-electron/package.json` 中声明了 ee-core、electron-updater、electron-builder、better-sqlite3 重建工具等。 该文档聚焦于“如何构建、如何打包、如何发布”,而不是完整业务代码分析。读者应能据此理解 dev、build、start、build-w/m/l 等命令的执行顺序,并知道在本地或 CI 中生成可分发的安装包。 ## 项目结构总览 ```mermaid graph TB subgraph "ai-electron" P["package.json
版本、scripts、依赖"] EE["electron/main.ts
ElectronEgg 入口"] CFG["electron/config/*
默认配置、生产配置、窗口选项"] CMD["cmd/*
electron-builder 打包配置"] OUT["out/*
打包输出目录"] FE_BIN["frontend/bin/*
前端安装/构建/启动脚本"] end subgraph "前端" FE_PKG["frontend/package.json
pnpm + Vite"] end P --> EE P --> CMD P --> FE_BIN EE --> CFG CMD --> OUT FE_BIN --> FE_PKG ``` **图表来源** - [ai-electron/package.json:1-42](file://ai-electron/package.json#L1-L42) - [ai-electron/electron/main.ts:1-19](file://ai-electron/electron/main.ts#L1-L19) - [ai-electron/electron/config/config.default.ts:1-50](file://ai-electron/electron/config/config.default.ts#L1-L50) - [ai-electron/cmd/builder.json:1-57](file://ai-electron/cmd/builder.json#L1-L57) **章节来源** - [ai-electron/package.json:1-42](file://ai-electron/package.json#L1-L42) - [ai-electron/electron/main.ts:1-19](file://ai-electron/electron/main.ts#L1-L19) - [ai-electron/electron/config/config.default.ts:1-50](file://ai-electron/electron/config/config.default.ts#L1-L50) - [ai-electron/cmd/builder.json:1-57](file://ai-electron/cmd/builder.json#L1-L57) ## 构建脚本总览 `ai-electron/package.json` 中的 scripts 是客户端构建与发布的统一入口。核心命令如下: | 命令 | 作用 | 执行顺序与关键点 | |---|---|---| | `dev` | 开发模式运行客户端 | 调用 `ee-bin dev`,由 ElectronEgg 启动 Electron 主进程、加载 preload、渲染前端资源。 | | `start` | 启动已构建产物 | 调用 `ee-bin start`,直接启动打包后的主进程,不重新编译前端。 | | `build` | 完整构建并加密 | 依次执行:构建前端 → 构建 Electron → 对 ee-bin 进行字节码加密。 | | `build-frontend` | 仅构建前端 | 调用 `ee-bin build --cmds=frontend`,再通过 `ee-bin move --flag=frontend_dist` 移动前端构建产物。 | | `build-electron` | 仅构建 Electron | 调用 `ee-bin build --cmds=electron`,将 TypeScript 主进程编译为 JavaScript 并准备打包。 | | `build-w` | 构建 Windows 安装包 | 调用 `ee-bin build --cmds=win64`,最终由 electron-builder 生成 NSIS 安装包。 | | `build-we` | 构建 Windows 扩展目标 | 调用 `ee-bin build --cmds=win_e`,用于 Windows 特殊构建场景。 | | `build-m` | 构建 macOS ARM64 安装包 | 调用 `ee-bin build --cmds=mac_arm64`,对应 Apple Silicon 架构。 | | `build-m-x86` | 构建 macOS x86_64 安装包 | 调用 `ee-bin build --cmds=mac`,对应 Intel Mac。 | | `build-m-arm64` | 构建 macOS ARM64 安装包 | 与 `build-m` 等价,显式指定 `mac_arm64`。 | | `build-l` | 构建 Linux 安装包 | 调用 `ee-bin build --cmds=linux`,最终生成 deb 包。 | | `re-sqlite` | 重建 better-sqlite3 | 调用 `electron-rebuild -f -w better-sqlite3`,解决原生模块 ABI 不匹配问题。 | | `icon` | 图标处理 | 调用 `ee-bin icon`,属于 ElectronEgg 提供的辅助能力。 | | `test` / `test:watch` | 单元测试 | 使用 Vitest。 | | `typecheck` | TypeScript 类型检查 | 使用 `tsc --noEmi`。 | 从依赖角度看,这些命令依赖以下外部组件: - **ee-core / ee-bin**:ElectronEgg 框架,负责应用生命周期、主进程启动、构建编排、字节码加密。 - **electron**:Electron 运行时。 - **electron-builder**:跨平台打包器,根据 `cmd/builder*.json` 生成安装包。 - **electron-updater**:客户端自动更新库,通过 `generic` provider 对接更新服务器。 - **@electron/rebuild**:用于重建 native addon,典型场景是 better-sqlite3。 **章节来源** - [ai-electron/package.json:1-42](file://ai-electron/package.json#L1-L42) ## 前端构建流程 ### 前端脚本职责 前端目录下 `frontend/bin` 中的脚本主要用于本地开发体验,它们不是 Electron 打包的主路径,但有助于理解前端构建过程。 | 脚本 | 用途 | 行为 | |---|---|---| | `install.sh` | 前端依赖安装 | 切换到前端根目录执行 `pnpm install`,再回到 `bin`。 | | `build.sh` | 前端构建 | 切换到前端根目录执行 `pnpm build`,再回到 `bin`。 | | `startup.sh` | 前端开发启动 | 切换到前端根目录执行 `pnpm dev`,再回到 `bin`。 | | `install.bat` | Windows 前端依赖安装 | 切换盘符与目录后执行 `npm run install`,然后暂停。 | | `build.bat` | Windows 前端构建 | 切换盘符与目录后执行 `npm run build`,然后暂停。 | | `startup.bat` | Windows 前端开发启动 | 切换盘符与目录后执行 `pnpm dev`,然后暂停。 | 需要注意:Windows 批处理脚本中混用了 `npm run install` 和 `pnpm dev`;实际使用时应优先确保 Node 包管理器一致。推荐在 CI 和本地都固定使用 pnpm,避免锁文件和依赖解析差异。 ### 前端与 Electron 的关系 在 Electron 主配置中,前端静态资源通过 mainServer 指向 `/public/dist/index.html`。也就是说: 1. 前端先被构建到 `frontend/dist`。 2. Electron 主进程以 file 协议加载该 HTML。 3. 打包时,前端构建产物会被纳入 Electron 应用资源。 ```mermaid flowchart TD Start["开始"] --> InstallFE["安装前端依赖"] InstallFE --> BuildFE["前端构建 pnpm build"] BuildFE --> Dist["产出 frontend/dist"] Dist --> LoadMain["Electron 主进程加载 /public/dist/index.html"] LoadMain --> AppReady["ElectronEgg 应用就绪"] AppReady --> End["客户端运行"] ``` **图表来源** - [ai-electron/electron/config/config.default.ts:1-50](file://ai-electron/electron/config/config.default.ts#L1-L50) - [ai-electron/frontend/bin/build.sh:1-5](file://ai-electron/frontend/bin/build.sh#L1-L5) - [ai-electron/frontend/bin/startup.sh:1-5](file://ai-electron/frontend/bin/startup.sh#L1-L5) **章节来源** - [ai-electron/frontend/bin/build.sh:1-5](file://ai-electron/frontend/bin/build.sh#L1-L5) - [ai-electron/frontend/bin/install.sh:1-5](file://ai-electron/frontend/bin/install.sh#L1-L5) - [ai-electron/frontend/bin/startup.sh:1-5](file://ai-electron/frontend/bin/startup.sh#L1-L5) - [ai-electron/frontend/bin/install.bat:1-9](file://ai-electron/frontend/bin/install.bat#L1-L9) - [ai-electron/frontend/bin/build.bat:1-9](file://ai-electron/frontend/bin/build.bat#L1-L9) - [ai-electron/frontend/bin/startup.bat:1-9](file://ai-electron/frontend/bin/startup.bat#L1-L9) - [ai-electron/electron/config/config.default.ts:1-50](file://ai-electron/electron/config/config.default.ts#L1-L50) ## Electron 打包流程 ### 完整构建链 `build` 命令定义了完整的 Electron 客户端构建链: ```mermaid flowchart TD A["npm run build"] --> B["build-frontend
ee-bin build --cmds=frontend"] B --> C["move frontend_dist
ee-bin move --flag=frontend_dist"] C --> D["build-electron
ee-bin build --cmds=electron"] D --> E["encrypt
ee-bin encrypt"] E --> F["打包产物进入 out 目录"] ``` **图表来源** - [ai-electron/package.json:1-42](file://ai-electron/package.json#L1-L42) 执行顺序可以理解为: 1. **前端构建**:通过 `ee-bin build --cmds=frontend` 构建前端资源。 2. **前端产物移动**:通过 `ee-bin move --flag=frontend_dist` 把前端构建产物移动到 Electron 应用期望的位置。 3. **Electron 构建**:通过 `ee-bin build --cmds=electron` 编译主进程 TypeScript。 4. **字节码加密**:通过 `ee-bin encrypt` 对 ee-bin 相关代码进行加密,增强分发安全性。 5. **打包**:后续 `build-w`、`build-m`、`build-l` 会触发 electron-builder,读取 `cmd/builder*.json` 生成安装包。 ### Electron 主进程启动 Electron 入口由 package.json 的 main 字段指向 `./public/electron/main.js`,而源码位于 `electron/main.ts`。启动流程大致为: ```mermaid sequenceDiagram participant OS as "操作系统" participant EE as "ElectronEgg" participant Main as "main.ts" participant Life as "Lifecycle" participant Win as "主窗口" OS->>EE: 启动 Electron 应用 EE->>Main: 加载主进程入口 Main->>EE: new ElectronEgg() Main->>Life: 注册 ready、electron-app-ready、window-ready、before-close Main->>EE: register(preload) Main->>EE: app.run() EE->>Life: ready() EE->>Life: electronAppReady() EE->>Win: 创建主窗口 EE->>Life: windowReady() ``` **图表来源** - [ai-electron/electron/main.ts:1-19](file://ai-electron/electron/main.ts#L1-L19) - [ai-electron/electron/preload/lifecycle.ts:1-73](file://ai-electron/electron/preload/lifecycle.ts#L1-L73) **章节来源** - [ai-electron/package.json:1-42](file://ai-electron/package.json#L1-L42) - [ai-electron/electron/main.ts:1-19](file://ai-electron/electron/main.ts#L1-L19) - [ai-electron/electron/preload/lifecycle.ts:1-73](file://ai-electron/electron/preload/lifecycle.ts#L1-L73) ## 三端产物差异 ### Windows Windows 打包配置定义在 `cmd/builder.json` 中,目标为 NSIS 安装包。关键特征包括: - 产品名称为 `qingjian-ai-client`。 - 应用 ID 为 `com.zsjz.qingjian.client`。 - 输出目录为 `out`。 - 使用 asar 打包应用资源。 - 语言包包含英文和中文。 - NSIS 安装器非一键安装,允许提升权限、自定义安装目录。 - 创建桌面快捷方式和开始菜单快捷方式。 - 快捷方式名称为“清鉴线索调查工具”。 - artifactName 使用 `${productName}-${os}-${version}-${arch}.${ext}` 模板。 - target 为 nsis。 ```mermaid flowchart TD WStart["build-w / build-we"] --> WBuilder["electron-builder 读取 builder.json"] WBuilder --> WNSIS["生成 NSIS 安装包"] WNSIS --> WOut["写入 ai-electron/out"] ``` **图表来源** - [ai-electron/cmd/builder.json:1-57](file://ai-electron/cmd/builder.json#L1-L57) ### macOS macOS 有两个构建配置文件: - `builder-mac.json`:通用 macOS 配置。 - `builder-mac-arm64.json`:ARM64 专用配置。 当前这两个文件的 productName 仍为 `ee`,appId 仍为 `com.bilibili.ee`,与主项目的 `qingjian-ai-client` 不一致。这是发布时需要特别注意的配置差异:如果直接使用这些模板,可能产生不符合产品命名和签名预期的产物。 macOS 配置的关键点: - asar 打包。 - electronLanguages 包含 en-US 和 zh-CN。 - extraResources 将 `build/extraResources` 映射到应用资源目录。 - publish 使用 generic provider,URL 为空。 - mac.target 未显式指定,默认由 electron-builder 推断。 - darkModeSupport 开启。 - hardenedRuntime 关闭。 ```mermaid flowchart TD MStart["build-m / build-m-arm64 / build-m-x86"] --> MBuilder["electron-builder 读取 mac 配置"] MBuilder --> MApp["生成 macOS 应用包"] MApp --> MOut["写入 ai-electron/out"] ``` **图表来源** - [ai-electron/cmd/builder-mac.json:1-34](file://ai-electron/cmd/builder-mac.json#L1-L34) - [ai-electron/cmd/builder-mac-arm64.json:1-34](file://ai-electron/cmd/builder-mac-arm64.json#L1-L34) ### Linux Linux 打包配置定义在 `cmd/builder.json` 和 `cmd/builder-linux.json` 中,目标为 deb。关键特征包括: - productName 为 `qingjian-ai-client`。 - appId 为 `com.zsjz.qingjian.client`。 - output 目录为 `out`。 - asar 启用。 - electronLanguages 包含 en-US 和 zh-CN。 - linux.target 为 deb。 - category 为 Utility。 - artifactName 同样使用 `${productName}-${os}-${version}-${arch}.${ext}` 模板。 - publish 使用 generic provider,URL 为空。 ```mermaid flowchart TD LStart["build-l"] --> LBuilder["electron-builder 读取 linux 配置"] LBuilder --> LDeb["生成 deb 安装包"] LDeb --> LOut["写入 ai-electron/out"] ``` **图表来源** - [ai-electron/cmd/builder.json:1-57](file://ai-electron/cmd/builder.json#L1-L57) - [ai-electron/cmd/builder-linux.json:1-41](file://ai-electron/cmd/builder-linux.json#L1-L41) ### 三端产物对比表 | 平台 | 主要命令 | 主要目标 | 产物模板 | 备注 | |---|---|---|---|---| | Windows | `build-w`、`build-we` | NSIS 安装包 | `${productName}-${os}-${version}-${arch}.${ext}` | 支持提权、自定义安装路径、桌面快捷方式 | | macOS | `build-m`、`build-m-arm64`、`build-m-x86` | macOS 应用包 | `${productName}-${os}-${version}-${arch}.${ext}` | 当前模板 productName/appId 与主产品不一致,需核对 | | Linux | `build-l` | deb 包 | `${productName}-${os}-${version}-${arch}.${ext}` | 分类为 Utility | **章节来源** - [ai-electron/cmd/builder.json:1-57](file://ai-electron/cmd/builder.json#L1-L57) - [ai-electron/cmd/builder-linux.json:1-41](file://ai-electron/cmd/builder-linux.json#L1-L41) - [ai-electron/cmd/builder-mac.json:1-34](file://ai-electron/cmd/builder-mac.json#L1-L34) - [ai-electron/cmd/builder-mac-arm64.json:1-34](file://ai-electron/cmd/builder-mac-arm64.json#L1-L34) ## 自动更新与版本号管理 ### 依赖关系 `ai-electron/package.json` 中声明了 `electron-updater`,这表明客户端具备基于 electron-updater 的自动更新能力。更新机制通常由 Electron 主进程在应用启动或用户主动检查更新时触发。 ### 更新服务器配置 electron-builder 的 publish 配置位于 `cmd/builder.json` 和 `builder-linux.json` 等文件中,统一使用: ```json { "provider": "generic", "url": "" } ``` 这意味着: - 更新服务器类型为 generic。 - 当前 URL 为空,表示未绑定正式更新地址。 - 发布时需要将 latest.yml、增量更新包、完整安装包部署到可公开访问的服务器。 - electron-updater 会根据 published URL 下载更新元数据和包。 ### 版本号来源 `ai-electron/package.json` 中声明的版本为 `200.0.0`。electron-builder 通常会读取 package.json 的 version 作为安装包版本,并据此生成 latest.yml。因此: - 发版前应确认 package.json 中的 version 与期望发布版本一致。 - 不要只修改 latest.yml 而不升级 package.json,否则会出现元数据与实际包名不一致的问题。 - 如果使用 CI 自动生成版本号,应在构建阶段注入版本号,并确保 package.json、latest.yml、安装包文件名三者一致。 ### 增量更新与回滚 当前仓库中没有看到 electron-updater 的前端或主进程实现细节,但结合 electron-updater 和 generic provider,常见行为如下: - 首次发布:需要上传完整安装包和 latest.yml。 - 后续发布:如果 electron-updater 启用增量更新,应上传 diff 包和新的 latest.yml。 - 回滚策略: - 若新版本存在严重问题,可将 latest.yml 恢复为上一个稳定版本的记录。 - 同时保留旧版本安装包供手动下载安装。 - 如果后端或客户端逻辑不兼容,应避免强制升级到有问题的版本。 - 对于无法自动回滚的情况,可提供“禁用更新”“选择版本安装”等降级手段。 ```mermaid flowchart TD Client["客户端"] --> Check["检查更新"] Check --> Server["更新服务器"] Server --> Meta["返回 latest.yml"] Meta --> Diff{"是否需要增量更新"} Diff -->|是| DownloadDiff["下载增量补丁"] Diff -->|否| DownloadFull["下载完整安装包"] DownloadDiff --> Install["安装更新"] DownloadFull --> Install Install --> Success["更新成功"] Install --> Rollback["出现异常时回滚或提示卸载重装"] ``` **图表来源** - [ai-electron/package.json:1-42](file://ai-electron/package.json#L1-L42) - [ai-electron/cmd/builder.json:1-57](file://ai-electron/cmd/builder.json#L1-L57) **章节来源** - [ai-electron/package.json:1-42](file://ai-electron/package.json#L1-L42) - [ai-electron/cmd/builder.json:1-57](file://ai-electron/cmd/builder.json#L1-L57) ## 本地与 CI 发布指南 ### 本地构建步骤 #### 开发调试 1. 在 `ai-electron` 目录下安装依赖。 2. 如需前端独立开发,可使用前端脚本安装依赖并启动前端开发服务。 3. 使用 `npm run dev` 或 `pnpm dev` 启动 Electron 客户端。 4. 如需仅启动 Electron 主进程而不重新构建前端,可使用 `npm run start` 或 `pnpm start`。 #### 完整构建 ```text cd ai-electron npm run build ``` 等价于: ```text npm run build-frontend npm run build-electron ee-bin encrypt ``` #### 生成各平台安装包 | 平台 | 命令 | |---|---| | Windows | `npm run build-w` | | macOS ARM64 | `npm run build-m` 或 `npm run build-m-arm64` | | macOS x86_64 | `npm run build-m-x86` | | Linux | `npm run build-l` | #### 产物位置 打包输出目录由 electron-builder 配置决定,位于 `ai-electron/out`。Windows 通常生成 NSIS 安装包,Linux 通常生成 deb 包,macOS 生成应用包。 ### CI 构建建议 CI 中建议明确以下步骤: 1. 固定 Node.js 版本,建议使用与 Electron 兼容的版本。 2. 固定 pnpm 版本,避免依赖解析差异。 3. 缓存 node_modules,缩短构建时间。 4. 分别构建 Windows、macOS、Linux 产物。 5. 上传安装包到制品库或更新服务器。 6. 更新服务器部署 latest.yml 和对应版本安装包。 7. 如需要签名和公证,应在对应平台构建任务中完成。 ```mermaid flowchart TD CI["CI 触发"] --> Checkout["检出代码"] Checkout --> SetupNode["设置 Node/pnpm 版本"] SetupNode --> InstallDeps["安装 ai-electron 依赖"] InstallDeps --> BuildFrontend["构建前端"] BuildFrontend --> BuildElectron["构建 Electron"] BuildElectron --> Encrypt["字节码加密"] Encrypt --> PackageWin["打包 Windows"] Encrypt --> PackageMac["打包 macOS"] Encrypt --> PackageLinux["打包 Linux"] PackageWin --> Upload["上传产物"] PackageMac --> Upload PackageLinux --> Upload Upload --> Publish["发布到更新服务器"] ``` **图表来源** - [ai-electron/package.json:1-42](file://ai-electron/package.json#L1-L42) - [ai-electron/cmd/builder.json:1-57](file://ai-electron/cmd/builder.json#L1-L57) **章节来源** - [ai-electron/package.json:1-42](file://ai-electron/package.json#L1-L42) - [ai-electron/cmd/builder.json:1-57](file://ai-electron/cmd/builder.json#L1-L57) ## 常见问题排查 ### Node 版本不匹配 **现象** - 安装依赖时报错。 - Electron 或 ee-bin 无法启动。 - 某些原生模块编译失败。 **原因** Electron 对 Node.js 版本有较强约束。不同 Electron 版本内置的 Node 版本不同,项目使用 Electron ^37.x,应使用与之兼容的 Node.js LTS 版本。 **处理方法** 1. 查看 Electron 对应的 Node 版本要求。 2. 在项目根目录或 CI 环境中固定 Node 版本。 3. 清理旧的 node_modules 和构建缓存后重试。 4. 如果已经安装了错误版本的原生模块,尝试重建。 ### better-sqlite3 重建失败 **现象** 启动时报 missing module、ABI mismatch、native addon 加载失败等错误。 **原因** better-sqlite3 是 native addon,必须使用与 Electron 匹配的 Node ABI 编译。如果 Node 版本变化、Electron 版本变化,或 CI 环境缓存不一致,就可能失败。 **处理方法** ```text npm run re-sqlite ``` 该命令等价于: ```text electron-rebuild -f -w better-sqlite3 ``` 如果仍然失败,可尝试: 1. 删除 node_modules 和缓存。 2. 重新安装依赖。 3. 确认使用的 Node 版本与 Electron 兼容。 4. 在 CI 中增加重建步骤,而不是复用其他平台的依赖缓存。 **章节来源** - [ai-electron/package.json:1-42](file://ai-electron/package.json#L1-L42) ### 前端构建失败 **现象** - `pnpm build` 报错。 - 找不到 TypeScript、Vite 或其他前端依赖。 - 构建产物缺失,导致 Electron 打开空白页。 **处理方法** 1. 确认前端依赖已安装:`pnpm install`。 2. 确认前端脚本路径正确:`frontend/bin/build.sh` 会进入前端目录执行 `pnpm build`。 3. 确认前端构建产物进入 Electron 可加载的目录。 4. 如果是 pnpm/npm 混用导致的锁文件问题,建议统一使用 pnpm。 **章节来源** - [ai-electron/frontend/bin/build.sh:1-5](file://ai-electron/frontend/bin/build.sh#L1-L5) - [ai-electron/frontend/bin/install.sh:1-5](file://ai-electron/frontend/bin/install.sh#L1-L5) - [ai-electron/frontend/bin/build.bat:1-9](file://ai-electron/frontend/bin/build.bat#L1-L9) - [ai-electron/frontend/bin/install.bat:1-9](file://ai-electron/frontend/bin/install.bat#L1-L9) ### 签名/公证失败 **现象** - macOS 应用无法打开,提示未验证开发者。 - 安装器签名失败。 - Gatekeeper 阻止运行。 **原因** macOS 签名和公证需要有效的开发者证书、Apple ID、正确的 Bundle Identifier 以及合适的代码签名配置。当前 macOS 打包配置中 `hardenedRuntime` 为 false,且 productName 和 appId 与主项目不一致,容易引发签名预期不符。 **处理方法** 1. 修正 macOS 打包配置中的 productName、appId,使其与产品身份一致。 2. 在 CI 中注入 Apple Developer Certificate、Provisioning Profile。 3. 如需 hardened runtime 和 Notarization,需在 electron-builder 配置中开启并提供相应凭据。 4. 先在本地测试签名流程,再集成到 CI。 **章节来源** - [ai-electron/cmd/builder-mac.json:1-34](file://ai-electron/cmd/builder-mac.json#L1-L34) - [ai-electron/cmd/builder-mac-arm64.json:1-34](file://ai-electron/cmd/builder-mac-arm64.json#L1-L34) ### 更新服务器地址配置错误 **现象** - 客户端检查更新失败。 - 下载 latest.yml 或安装包超时。 - 版本号不一致导致更新失败。 **原因** 当前 electron-builder 的 publish URL 为空,意味着没有绑定正式更新服务器地址。此外,electron-updater 的更新行为还可能受运行时配置影响。 **处理方法** 1. 在 electron-builder 的 publish 配置中填写可用的 generic 更新服务器地址。 2. 确保服务器上存在 latest.yml 和对应版本安装包。 3. 确保 package.json 的 version 与 latest.yml 中的 version 一致。 4. 确保安装包文件名符合 electron-builder 的 artifactName 规则。 5. 如果更新服务器在内网,需保证客户端网络可达。 6. 如果更新接口需要认证,应按 electron-updater 文档配置请求头或鉴权参数。 **章节来源** - [ai-electron/cmd/builder.json:1-57](file://ai-electron/cmd/builder.json#L1-L57) - [ai-electron/package.json:1-42](file://ai-electron/package.json#L1-L42) ### 主窗口显示异常或白屏 **现象** - 主窗口尺寸异常。 - 窗口重复实例。 - 前端页面空白。 **原因** 主窗口尺寸计算依赖屏幕 workAreaSize,并在 windowReady 中设置 bounds。同时,lifecycle 中处理 second-instance 事件,优先聚焦智能工作台窗口,否则聚焦主窗口。 **处理方法** 1. 检查主屏幕分辨率和多显示器环境。 2. 检查是否重复启动客户端。 3. 检查前端构建产物是否正确加载。 4. 检查 `config.default.ts` 中 mainServer 的 indexPath 是否指向有效前端页面。 **章节来源** - [ai-electron/electron/preload/lifecycle.ts:1-73](file://ai-electron/electron/preload/lifecycle.ts#L1-L73) - [ai-electron/electron/config/config.default.ts:1-50](file://ai-electron/electron/config/config.default.ts#L1-L50) ## 最佳实践与建议 1. **统一包管理器** 前端脚本同时出现 npm 和 pnpm,建议在项目和 CI 中固定 pnpm,避免依赖树不一致。 2. **固定 Node 版本** 使用 `.nvmrc`、`.node-version` 或 CI 的 actions/setup-node 固定 Node 版本,确保 Electron、ee-core、better-sqlite3 的 ABI 一致。 3. **规范版本号管理** 所有发布应以 package.json 的 version 为准。CI 可通过命令行更新版本号,再触发构建。 4. **修正 macOS 打包模板** 当前 `builder-mac.json` 和 `builder-mac-arm64.json` 的 productName 和 appId 与主产品不一致,正式发布前必须修正,否则会影响签名、分发和更新。 5. **明确更新服务器** 将 electron-builder 的 publish URL 指向真实更新服务器,并在 CI 中部署 latest.yml 和安装包。 6. **区分开发、预发布、正式发布** - 开发:`dev` - 预发布:可单独构建前端或 Electron,便于快速验证。 - 正式发布:`build` + 三端打包 + 签名 + 公证 + 发布到更新服务器。 7. **保留回滚能力** 保留最近两个稳定版本的安装包和 latest.yml,以便出现问题时快速回退。 8. **自动化测试与类型检查** 在 CI 中执行 `typecheck`、`test`,减少发布风险。 9. **谨慎使用字节码加密** `ee-bin encrypt` 可以提升安全性,但也可能增加调试难度。建议在正式构建中使用,开发时使用 `dev`。 10. **关注 ElectronEgg 文档** 本项目大量依赖 ElectronEgg 的能力,包括生命周期、构建、加密、打包等。遇到 ee-bin 相关问题时,应参考 ElectronEgg 官方文档。 **章节来源** - [ai-electron/README.md:1-134](file://ai-electron/README.md#L1-L134) - [ai-electron/README.zh-CN.md:1-134](file://ai-electron/README.zh-CN.md#L1-L134) - [ai-electron/package.json:1-42](file://ai-electron/package.json#L1-L42) - [ai-electron/cmd/builder-mac.json:1-34](file://ai-electron/cmd/builder-mac.json#L1-L34) - [ai-electron/cmd/builder-mac-arm64.json:1-34](file://ai-electron/cmd/builder-mac-arm64.json#L1-L34)