简介

框架入口模块，初始化运行环境并启动应用。提供 ElectronEgg 类（框架引导）、EventBus 单例（生命周期与自定义事件）、Application 单例（启动编排）和五个生命周期常量（Ready、ElectronAppReady、WindowReady、BeforeClose、Preload）。

导入

// ESM — 从顶层入口导入
import { ElectronEgg, app, eventBus, EventBus, Ready, ElectronAppReady, WindowReady, BeforeClose, Preload } from 'ee-core';
// ESM — 从 app 子路径导入
import { ElectronEgg } from 'ee-core/app/boot';
import { eventBus, EventBus, Ready } from 'ee-core/app/events';
import { app, Application } from 'ee-core/app/application';

// CJS — 从顶层入口导入
const { ElectronEgg, app, eventBus, EventBus, Ready } = require('ee-core');
// CJS — 从 app 子路径导入
const { ElectronEgg } = require('ee-core/app/boot');
const { eventBus } = require('ee-core/app/events');
const { Application, app } = require('ee-core/app/application');

API

ElectronEgg

框架主类。在 electron/main.js 中实例化一次，收集 Electron 运行环境信息，写入全局环境变量，并按固定顺序初始化基础功能。

constructor()

说明：收集环境信息并初始化框架。执行流程：解析命令行参数（env、debugger），解析目录，构建 ElectronEggOptions，将关键信息写入 process.env，然后调用 init()。

返回值：ElectronEgg 实例，已设置 options 属性。

示例：

const electronEgg = new ElectronEgg();
// options.env, options.baseDir, options.electronDir 等已填充

init()

说明：初始化框架基础功能。加载顺序固定，不可更改：loadException → loadConfig → loadDir → loadLog。

返回值：void

register(eventName, handler)

说明：注册生命周期事件处理函数。委托给 app.register()，后者调用 eventBus.register()。如果事件名已注册，则覆盖之前的处理函数并输出警告日志。

参数：

参数	类型	必填	说明
eventName	string	是	生命周期事件名：Ready、ElectronAppReady、WindowReady、BeforeClose 或 Preload
handler	(...args: unknown[]) => void	是	事件处理函数；支持异步函数

返回值：void

示例：

import { ElectronEgg, BeforeClose } from 'ee-core';

const electronEgg = new ElectronEgg();
electronEgg.register(BeforeClose, async () => {
  // 窗口关闭前的清理逻辑
  console.log('App is about to close');
});
await electronEgg.run();

参见：EventBus.register

run()

说明：同步启动应用。流程：loadController()（同步 require()）→ loadSocket() → emitLifecycle(Ready) → loadElectron()。适用于 CJS 项目。

返回值：Promise<void>

示例：

const electronEgg = new ElectronEgg();
await electronEgg.run();

runAsync()

说明：异步启动应用。与 run() 流程相同，但控制器通过动态 import() 加载。适用于 ESM 项目。

返回值：Promise<void>

示例：

const electronEgg = new ElectronEgg();
await electronEgg.runAsync();

ElectronEggOptions

ElectronEgg 实例的 options 属性类型定义。在框架初始化期间构建，值在整个应用生命周期中不变。

属性	类型	说明
env	string	运行环境标识（如 'dev'、'prod'、'test'）
baseDir	string	项目根目录（package.json 所在目录）
electronDir	string	Electron 主进程源码目录
appName	string	来自 package.json 的应用名称
userHome	string	用户主目录（os.homedir()）
appData	string	系统级应用数据目录
appUserData	string	Electron 用户数据目录（appData/appName）
appVersion	string	来自 package.json 的应用版本
isPackaged	boolean	是否已打包为安装程序（app.isPackaged）
execDir	string	可执行文件目录；打包后指向 exe 路径

---

EventBus

事件总线类，分别管理生命周期事件和自定义事件。同时导出类和预创建的单例 eventBus。

register(eventName, handler)

说明：注册生命周期事件处理函数。生命周期事件由框架内部触发。如果同一事件名已注册，则覆盖旧的处理函数并输出警告日志。

参数：

参数	类型	必填	说明
eventName	string	是	生命周期事件名（使用常量：Ready、ElectronAppReady、WindowReady、BeforeClose、Preload）
handler	(...args: unknown[]) => unknown	是	处理函数；同步或异步

返回值：void

emitLifecycle(eventName, ...args)

说明：触发生命周期事件。同步处理函数的错误会传播到调用方。异步处理函数的错误会以未处理的拒绝重新抛出（由全局异常处理器捕获）。

参数：

参数	类型	必填	说明
eventName	string	是	生命周期事件名
args	unknown[]	否	传递给处理函数的参数

返回值：void

on(eventName, handler)

说明：注册自定义事件处理函数。业务代码可自由定义事件名并通过 emit() 触发。如果事件名已注册，则覆盖旧的处理函数并输出警告日志。

参数：

参数	类型	必填	说明
eventName	string	是	自定义事件名
handler	(...args: unknown[]) => unknown	是	处理函数；同步或异步

返回值：void

示例：

import { eventBus } from 'ee-core';

eventBus.on('customEvent', (payload) => {
  console.log('Received:', payload);
});

emit(eventName, ...args)

说明：触发自定义事件。处理函数中的同步异常和异步拒绝都会被自动捕获并记录日志——单个处理函数的错误不会影响其他逻辑。

参数：

参数	类型	必填	说明
eventName	string	是	自定义事件名
args	unknown[]	否	传递给处理函数的参数

返回值：void

示例：

import { eventBus } from 'ee-core';
eventBus.emit('customEvent', { key: 'value' });

---

eventBus（单例）

预创建的 EventBus 实例，全局共享。直接使用此单例，而非创建新的 EventBus 实例。

---

Application

框架启动流程编排器。同时导出类和预创建的单例 app。

register(eventName, handler)

说明：注册生命周期事件处理函数。委托给 eventBus.register()。

参数：

参数	类型	必填	说明
eventName	string	是	事件名（如 'ready'、'before-close'）
handler	(...args: unknown[]) => void	是	处理函数

返回值：void

run()

说明：同步启动应用。流程：loadController() → loadSocket() → emitLifecycle(Ready) → loadElectron()。

返回值：Promise<void>

runAsync()

说明：异步启动应用。与 run() 流程相同，但控制器通过 import() 加载。

返回值：Promise<void>

app（单例）

预创建的 Application 实例。由 ElectronEgg 内部使用；通常不在业务代码中直接使用。

---

生命周期常量

框架里程碑事件名，用作 register() 和 emitLifecycle() 的 eventName 参数。

常量	值	说明
Ready	'ready'	框架基础功能已加载（控制器、通信服务就绪）
ElectronAppReady	'electron-app-ready'	Electron app.whenReady() 已完成
WindowReady	'window-ready'	主窗口已创建
BeforeClose	'before-close'	窗口关闭前；可用于清理操作
Preload	'preload'	preload 脚本注入时机

参见：config、controller、socket、electron