本文引用的文件
本文面向 Electron 主进程与生命周期的维护者,说明 ai-electron 项目如何通过 ee-core.ElectronEgg 启动应用、注册生命周期钩子、执行预加载逻辑,并划分主进程与渲染进程的职责。重点覆盖以下文件:
ai-electron/electron/main.tsai-electron/electron/preload/lifecycle.tsai-electron/electron/preload/index.tsai-electron/electron/preload/bridge.tsai-electron/electron/config/windowOptions.ts、ai-electron/electron/service/window/smartWindow.tsai-electron/electron/controller/windowCtl.tsai-electron/package.jsonElectron 相关代码集中在 ai-electron/electron 下,采用按职责分层的方式组织:
graph TB
A["应用包入口<br/>ai-electron/package.json"] --> B["主进程入口<br/>electron/main.ts"]
B --> C["生命周期模块<br/>electron/preload/lifecycle.ts"]
B --> D["预加载函数<br/>electron/preload/index.ts"]
D --> E["托盘服务<br/>service/os/tray(由 index.ts 引用)"]
D --> F["安全服务<br/>service/os/security(由 index.ts 引用)"]
C --> G["智能工作台服务<br/>service/window/smartWindow.ts"]
C --> H["主窗口获取能力<br/>ee-core/electron.getMainWindow"]
I["窗口配置<br/>electron/config/windowOptions.ts"] --> G
J["窗口控制器<br/>electron/controller/windowCtl.ts"] --> G
图示来源
章节来源
main.ts 通过 new ElectronEgg() 创建应用对象,并由其统一调度生命周期和预加载。ready、electron-app-ready、window-ready、before-close 四个生命周期钩子,分别承担初始化日志、双实例聚焦、主窗口尺寸与显示策略、关闭前清理等职责。contextBridge 向渲染进程暴露 electron.ipcRenderer。ee-core 提供的 getMainWindow、IPC 控制器和智能工作台服务管理主窗口及工作区窗口。章节来源
Electron 应用的生命周期从包入口进入主进程,再由 ElectronEgg 驱动;预加载阶段负责系统服务初始化;渲染进程通过 IPC 或桥接接口调用主进程能力。
sequenceDiagram
participant Pkg as "package.json"
participant Main as "main.ts"
participant Egg as "ee-core.ElectronEgg"
participant Life as "Lifecycle"
participant Preload as "preload/index.ts"
participant Tray as "托盘服务"
participant Sec as "安全服务"
participant Win as "主窗口/智能窗口"
Pkg->>Main: 指定 main 入口
Main->>Egg: new ElectronEgg()
Main->>Life: new Lifecycle()
Main->>Egg: register("ready", life.ready)
Main->>Egg: register("electron-app-ready", life.electronAppReady)
Main->>Egg: register("window-ready", life.windowReady)
Main->>Egg: register("before-close", life.beforeClose)
Main->>Egg: register("preload", preload)
Egg-->>Main: app.run()
Egg->>Life: ready()
Egg->>Life: electronAppReady()
Egg->>Preload: preload()
Preload->>Tray: create()
Preload->>Sec: create()
Egg->>Life: windowReady()
Life->>Win: 设置位置/大小/显示策略
图示来源
main.ts 的职责非常集中:
ElectronEgg、Lifecycle 和 preload。readyelectron-app-readywindow-readybefore-closepreload。app.run() 启动应用。该文件不直接操作窗口,而是把窗口行为交给 Lifecycle 和 ee-core 提供的能力。
章节来源
Lifecycle 类定义了四个异步方法,对应 ElectronEgg 的命名事件。它们的职责如下:
| 钩子 | 触发时机 | 主要职责 | 关键依赖 |
|---|---|---|---|
ready |
核心应用已加载完成 | 记录生命周期日志 | ee-core/log.logger |
electron-app-ready |
Electron 应用就绪 | 处理双击图标重复启动、聚焦主窗口或智能工作台 | electron.app、ee-core/electron.getMainWindow、focusSmartWindow |
window-ready |
主窗口已加载 | 计算主窗口居中位置和比例大小;根据配置决定是否延迟显示 | screen、getConfig、getMainWindow |
before-close |
应用即将关闭 | 记录关闭日志 | logger |
flowchart TD
Start(["应用启动"]) --> Ready["生命周期:ready"]
Ready --> AppReady["生命周期:electron-app-ready"]
AppReady --> SecondInstance{"是否二次实例?"}
SecondInstance -->|是| FocusSmartOrMain["尝试聚焦智能工作台<br/>失败则聚焦主窗口"]
SecondInstance -->|否| WaitWindow["等待主窗口加载"]
WaitWindow --> WindowReady["生命周期:window-ready"]
WindowReady --> CalcSize["计算屏幕工作区与窗口尺寸"]
CalcSize --> SetBounds["设置主窗口位置与大小"]
SetBounds --> ShowStrategy{"是否隐藏初始显示?"}
ShowStrategy -->|是| DelayShow["监听 ready-to-show 再显示并聚焦"]
ShowStrategy -->|否| NormalShow["正常显示"]
DelayShow --> BeforeClose["生命周期:before-close"]
NormalShow --> BeforeClose
BeforeClose --> End(["应用退出流程"])
图示来源
章节来源
preload/index.ts 中的 preload() 函数在预加载阶段执行,主要动作是:
trayService.create() 创建托盘服务。securityService.create() 创建安全服务。这说明预加载阶段的核心职责是初始化系统级服务,而不是承载业务 UI 逻辑。托盘和安全服务通常用于菜单、通知、权限、加密、证书或平台能力。
sequenceDiagram
participant Egg as "ElectronEgg"
participant Preload as "preload/index.ts"
participant Tray as "托盘服务"
participant Sec as "安全服务"
Egg->>Preload: 调用 preload()
Preload->>Tray: create()
Preload->>Sec: create()
Preload-->>Egg: 预加载完成
图示来源
章节来源
bridge.ts 在启用上下文隔离时,通过 contextBridge.exposeInMainWorld 向渲染进程暴露全局 electron 对象,其中包含 ipcRenderer。这表示:
contextIsolation 启用时,渲染进程不能直接访问 Electron API。当前 windowOptions.ts 中 sharedWebPreferences 使用 contextIsolation: false 和 nodeIntegration: true,因此渲染进程可直接使用 Node 和 Electron API;但桥接仍可作为兼容层存在。
classDiagram
class Bridge {
+exposeInMainWorld("electron")
+ipcRenderer
}
class RendererProcess {
+使用全局 electron.ipcRenderer
+调用主进程 IPC
}
Bridge <.. RendererProcess : "暴露能力"
图示来源
章节来源
主进程负责:
渲染进程只负责:
根据主进程返回的状态更新界面。
graph LR
UI["渲染进程 UI"] --> IPC["IPC 控制器<br/>controller/windowCtl.ts"]
IPC --> Smart["智能工作台服务<br/>service/window/smartWindow.ts"]
Smart --> Browser["BrowserWindow"]
UI -.-> Bridge["bridge.ts contextBridge"]
图示来源
章节来源
主进程入口依赖 ee-core 的应用框架、生命周期模块和预加载函数;生命周期模块依赖 Electron 原生 API、日志、配置和窗口服务;预加载模块依赖托盘服务与安全服务;窗口配置与控制器共同支撑智能工作台行为。
graph TB
Main["main.ts"] --> Core["ee-core.ElectronEgg"]
Main --> Life["Lifecycle"]
Main --> PreloadFn["preload/index.ts"]
Life --> ElectronAPI["electron.app / screen"]
Life --> EECore["ee-core/log / config / getMainWindow"]
Life --> SmartSvc["service/window/smartWindow.ts"]
PreloadFn --> Tray["service/os/tray"]
PreloadFn --> Security["service/os/security"]
Config["config/windowOptions.ts"] --> SmartSvc
Controller["controller/windowCtl.ts"] --> SmartSvc
图示来源
章节来源
window-ready 中基于主显示器工作区计算窗口宽高,避免全屏铺满导致的视觉拥挤。ready-to-show 后才显示并聚焦,减少白屏感知。章节来源
可能原因:
main 指向错误。ElectronEgg 初始化或 app.run() 未执行。排查步骤:
package.json 的 main 字段是否指向编译后的主进程入口。main.ts 确实创建了 ElectronEgg 并调用了 app.run()。public/electron/main.js。章节来源
可能原因:
register 调用不一致。排查步骤:
main.ts 中注册的钩子名是否与 Lifecycle 方法一致。章节来源
可能原因:
排查步骤:
preload/index.ts 中托盘服务与安全服务的导入路径。preload load 1 与 preload load 2。章节来源
可能原因:
排查步骤:
preload() 中先执行托盘创建,再执行安全服务创建,便于定位具体失败点。create() 抛出的异常并记录日志。章节来源
可能原因:
window-ready 未正确设置窗口位置与大小。ready-to-show 未触发或逻辑分支异常。排查步骤:
window-ready 是否成功获取主窗口和屏幕信息。getConfig().windowsOption.show 是否影响显示策略。ready-to-show 回调日志,确认窗口最终显示时机。章节来源
可能原因:
second-instance 事件未注册。getMainWindow() 返回空窗口。排查步骤:
electron-app-ready 中是否注册 second-instance。focusSmartWindow() 是否返回 true。章节来源
该项目的 Electron 主进程以 ee-core.ElectronEgg 为中心,通过清晰的命名事件注册生命周期,将应用启动、窗口管理和系统能力初始化解耦。Lifecycle 负责应用级生命周期,preload 负责系统服务初始化,窗口与 IPC 控制器负责窗口行为和跨窗口通信。这种结构便于扩展新的生命周期钩子和预加载逻辑,同时保持主进程与渲染进程职责清晰。
推荐步骤:
Lifecycle 类中新增异步方法,例如 myHook。main.ts 中通过 app.register("my-hook-name", life.myHook) 注册。注意:
register 传入的名称一致。window-ready 之后,或使用 getMainWindow() 安全获取。preload 之后,或通过主进程服务重新初始化。章节来源
推荐步骤:
preload/index.ts 的 preload() 中增加初始化逻辑。create() 方法,并在其中捕获异常并记录日志。bridge.ts 中扩展全局对象,并结合 windowOptions.ts 的 webPreferences 配置。注意事项:
contextBridge 暴露能力,而不是直接使用 Electron API。章节来源