Electron 主进程与生命周期.md 20 KB

Electron 主进程与生命周期

本文引用的文件

  • main.ts
  • lifecycle.ts
  • index.ts(预加载入口)
  • bridge.ts
  • package.json
  • windowOptions.ts
  • windowCtl.ts
  • smartWindow.ts

目录

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与行为特性
  8. 常见问题排查
  9. 结论
  10. 附录:新增生命周期与自定义预加载步骤

引言

本文面向 Electron 主进程与生命周期的维护者,说明 ai-electron 项目如何通过 ee-core.ElectronEgg 启动应用、注册生命周期钩子、执行预加载逻辑,并划分主进程与渲染进程的职责。重点覆盖以下文件:

  • 主进程入口:ai-electron/electron/main.ts
  • 生命周期实现:ai-electron/electron/preload/lifecycle.ts
  • 预加载入口:ai-electron/electron/preload/index.ts
  • 上下文桥接:ai-electron/electron/preload/bridge.ts
  • 窗口配置与服务:ai-electron/electron/config/windowOptions.ts、ai-electron/electron/service/window/smartWindow.ts
  • 控制器与 IPC:ai-electron/electron/controller/windowCtl.ts
  • 应用元信息:ai-electron/package.json

项目结构

Electron 相关代码集中在 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

图示来源

  • package.json:1-42
  • main.ts:1-19
  • lifecycle.ts:1-73
  • index.ts(预加载入口):1-16
  • windowOptions.ts:1-41
  • windowCtl.ts:1-123
  • smartWindow.ts:1-200

章节来源

  • package.json:1-42
  • main.ts:1-19

核心组件

  • ElectronEgg 应用实例:main.ts 通过 new ElectronEgg() 创建应用对象,并由其统一调度生命周期和预加载。
  • Lifecycle 类:封装 ready、electron-app-ready、window-ready、before-close 四个生命周期钩子,分别承担初始化日志、双实例聚焦、主窗口尺寸与显示策略、关闭前清理等职责。
  • preload() 函数:在预加载阶段创建托盘服务和安全服务,为后续渲染进程提供系统能力。
  • Bridge 暴露:在启用上下文隔离时,通过 contextBridge 向渲染进程暴露 electron.ipcRenderer。
  • 窗口与 IPC 能力:通过 ee-core 提供的 getMainWindow、IPC 控制器和智能工作台服务管理主窗口及工作区窗口。

章节来源

  • main.ts:1-19
  • lifecycle.ts:1-73
  • index.ts(预加载入口):1-16
  • bridge.ts:1-10
  • windowCtl.ts:1-123
  • smartWindow.ts:1-200

架构总览

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:1-19
  • lifecycle.ts:1-73
  • index.ts(预加载入口):1-16

详细组件分析

主进程入口:ElectronEgg 与应用启动

main.ts 的职责非常集中:

  1. 引入 ElectronEgg、Lifecycle 和 preload。
  2. 创建应用实例。
  3. 注册生命周期钩子:
    • ready
    • electron-app-ready
    • window-ready
    • before-close
  4. 注册预加载函数 preload。
  5. 调用 app.run() 启动应用。

该文件不直接操作窗口,而是把窗口行为交给 Lifecycle 和 ee-core 提供的能力。

章节来源

  • main.ts:1-19

生命周期钩子:执行顺序与职责边界

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(["应用退出流程"])

图示来源

  • lifecycle.ts:1-73

章节来源

  • lifecycle.ts:1-73

预加载阶段:托盘服务与安全服务

preload/index.ts 中的 preload() 函数在预加载阶段执行,主要动作是:

  1. 输出预加载日志。
  2. 调用 trayService.create() 创建托盘服务。
  3. 调用 securityService.create() 创建安全服务。
  4. 保留可选的跨语言服务初始化注释。

这说明预加载阶段的核心职责是初始化系统级服务,而不是承载业务 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: 预加载完成

图示来源

  • index.ts(预加载入口):1-16

章节来源

  • index.ts(预加载入口):1-16

渲染进程桥接:contextBridge 与 ipcRenderer

bridge.ts 在启用上下文隔离时,通过 contextBridge.exposeInMainWorld 向渲染进程暴露全局 electron 对象,其中包含 ipcRenderer。这表示:

  • 当 contextIsolation 启用时,渲染进程不能直接访问 Electron API。
  • 渲染进程应通过桥接对象或 IPC 控制器调用主进程能力。
  • 当前 windowOptions.ts 中 sharedWebPreferences 使用 contextIsolation: false 和 nodeIntegration: true,因此渲染进程可直接使用 Node 和 Electron API;但桥接仍可作为兼容层存在。

    classDiagram
    class Bridge {
        +exposeInMainWorld("electron")
        +ipcRenderer
    }
    
    class RendererProcess {
        +使用全局 electron.ipcRenderer
        +调用主进程 IPC
    }
    
    Bridge <.. RendererProcess : "暴露能力"
    

图示来源

  • bridge.ts:1-10

章节来源

  • bridge.ts:1-10
  • windowOptions.ts:1-41

窗口与 IPC:主进程职责边界

主进程负责:

  • 窗口生命周期与几何布局。
  • 智能工作台窗口的单例管理、位置恢复、崩溃重建。
  • 跨窗口状态同步。
  • 登录失效或授权失效时将主窗口拉至前台。

渲染进程只负责:

  • UI 展示。
  • 用户交互。
  • 通过 IPC 或桥接调用主进程能力。
  • 根据主进程返回的状态更新界面。

    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"]
    

图示来源

  • windowCtl.ts:1-123
  • smartWindow.ts:1-200
  • bridge.ts:1-10

章节来源

  • windowCtl.ts:1-123
  • smartWindow.ts:1-200

依赖关系分析

主进程入口依赖 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

图示来源

  • main.ts:1-19
  • lifecycle.ts:1-73
  • index.ts(预加载入口):1-16
  • windowOptions.ts:1-41
  • windowCtl.ts:1-123
  • smartWindow.ts:1-200

章节来源

  • main.ts:1-19
  • lifecycle.ts:1-73
  • index.ts(预加载入口):1-16

性能与行为特性

  • 主窗口居中与比例缩放:window-ready 中基于主显示器工作区计算窗口宽高,避免全屏铺满导致的视觉拥挤。
  • 延迟显示策略:当配置要求不立即显示时,主窗口在 ready-to-show 后才显示并聚焦,减少白屏感知。
  • 智能工作台单例:最多一个工作区窗口;已打开时优先聚焦,必要时重载或导航。
  • 崩溃恢复:智能窗口渲染进程崩溃后销毁空壳,下次重新创建,避免残留无效窗口。
  • 位置持久化:智能窗口关闭时保存 bounds,下次启动恢复,提升用户体验一致性。

章节来源

  • lifecycle.ts:1-73
  • smartWindow.ts:1-200

常见问题排查

主进程未启动

可能原因:

  • 包入口 main 指向错误。
  • ElectronEgg 初始化或 app.run() 未执行。
  • 构建产物路径不正确。

排查步骤:

  1. 检查 package.json 的 main 字段是否指向编译后的主进程入口。
  2. 确认 main.ts 确实创建了 ElectronEgg 并调用了 app.run()。
  3. 检查构建脚本是否生成了预期的 public/electron/main.js。

章节来源

  • package.json:1-42
  • main.ts:1-19

生命周期钩子未执行

可能原因:

  • 钩子名称与 register 调用不一致。
  • 钩子内部抛出异常,导致后续生命周期中断。
  • 主进程提前退出。

排查步骤:

  1. 核对 main.ts 中注册的钩子名是否与 Lifecycle 方法一致。
  2. 检查各钩子开头的日志输出是否出现。
  3. 将钩子内复杂逻辑拆分为独立函数,逐步定位异常。

章节来源

  • main.ts:1-19
  • lifecycle.ts:1-73

preload 加载失败

可能原因:

  • 托盘服务或安全服务导入路径错误。
  • 预加载模块中引用了渲染进程不可用的 API。
  • 预加载阶段初始化逻辑抛出异常。

排查步骤:

  1. 检查 preload/index.ts 中托盘服务与安全服务的导入路径。
  2. 确认预加载阶段没有直接操作 DOM 或渲染进程专属 API。
  3. 查看预加载日志是否打印出 preload load 1 与 preload load 2。

章节来源

  • index.ts(预加载入口):1-16

托盘或安全服务异常

可能原因:

  • 托盘服务未正确创建。
  • 安全服务初始化依赖缺失。
  • 平台差异导致系统能力不可用。

排查步骤:

  1. 在 preload() 中先执行托盘创建,再执行安全服务创建,便于定位具体失败点。
  2. 捕获服务 create() 抛出的异常并记录日志。
  3. 区分开发环境与生产环境的行为差异,特别是路径、证书、密钥和平台 API。

章节来源

  • index.ts(预加载入口):1-16

主窗口未显示或显示异常

可能原因:

  • window-ready 未正确设置窗口位置与大小。
  • 配置项控制窗口延迟显示。
  • ready-to-show 未触发或逻辑分支异常。

排查步骤:

  1. 检查 window-ready 是否成功获取主窗口和屏幕信息。
  2. 检查 getConfig().windowsOption.show 是否影响显示策略。
  3. 添加 ready-to-show 回调日志,确认窗口最终显示时机。

章节来源

  • lifecycle.ts:1-73

双击图标无法聚焦窗口

可能原因:

  • second-instance 事件未注册。
  • getMainWindow() 返回空窗口。
  • 智能工作台优先聚焦成功,但用户误以为主窗口未被拉起。

排查步骤:

  1. 检查 electron-app-ready 中是否注册 second-instance。
  2. 检查 focusSmartWindow() 是否返回 true。
  3. 若智能窗口已打开,预期行为是先聚焦智能窗口;只有失败时才聚焦主窗口。

章节来源

  • lifecycle.ts:1-73
  • smartWindow.ts:1-200

结论

该项目的 Electron 主进程以 ee-core.ElectronEgg 为中心,通过清晰的命名事件注册生命周期,将应用启动、窗口管理和系统能力初始化解耦。Lifecycle 负责应用级生命周期,preload 负责系统服务初始化,窗口与 IPC 控制器负责窗口行为和跨窗口通信。这种结构便于扩展新的生命周期钩子和预加载逻辑,同时保持主进程与渲染进程职责清晰。

附录:新增生命周期与自定义预加载步骤

新增生命周期钩子

推荐步骤:

  1. 在 Lifecycle 类中新增异步方法,例如 myHook。
  2. 在 main.ts 中通过 app.register("my-hook-name", life.myHook) 注册。
  3. 在钩子内部只做主进程侧初始化,避免直接操作渲染进程 UI。
  4. 添加日志,便于判断钩子是否执行以及执行顺序。

注意:

  • 钩子名称必须与 register 传入的名称一致。
  • 如果钩子依赖窗口,应放在 window-ready 之后,或使用 getMainWindow() 安全获取。
  • 如果钩子依赖预加载服务,应放在 preload 之后,或通过主进程服务重新初始化。

章节来源

  • main.ts:1-19
  • lifecycle.ts:1-73

自定义 preload 初始化

推荐步骤:

  1. 在 preload/index.ts 的 preload() 中增加初始化逻辑。
  2. 新增服务文件时,先写 create() 方法,并在其中捕获异常并记录日志。
  3. 托盘服务与安全服务建议分开初始化,便于定位失败点。
  4. 如需向渲染进程暴露能力,可在 bridge.ts 中扩展全局对象,并结合 windowOptions.ts 的 webPreferences 配置。

注意事项:

  • 预加载阶段不应执行耗时阻塞逻辑。
  • 不要假设渲染进程已可用。
  • 若启用上下文隔离,应通过 contextBridge 暴露能力,而不是直接使用 Electron API。

章节来源

  • index.ts(预加载入口):1-16
  • bridge.ts:1-10
  • windowOptions.ts:1-41