升级electron egg脚手架版本
This commit is contained in:
133
doc/便携式JRE集成指南.md
Normal file
133
doc/便携式JRE集成指南.md
Normal file
@@ -0,0 +1,133 @@
|
||||
## 便携式 JRE/JDK8 集成指南
|
||||
|
||||
本指南介绍如何将 JRE 8 以“便携式”（解压即用、无需安装）的方式随应用打包，并在 Electron 主进程中通过绝对路径调用，从而避免要求用户在系统中安装 JDK/JRE。
|
||||
|
||||
### 为什么选择便携式 JRE
|
||||
- 无需管理员权限与系统环境变量配置，用户无感知。
|
||||
- 不污染系统环境（不写入 JAVA_HOME/PATH）。
|
||||
- 跨平台一致，可精简体积、可控版本。
|
||||
|
||||
### 适用场景
|
||||
- 运行 Java 程序或 JAR 包（仅需运行时）。
|
||||
- 不需要 javac/jcmd/jmap 等开发/诊断工具（若需要，请改为随包便携式 JDK）。
|
||||
|
||||
### 推荐的 JRE 8 发行版（可再分发）
|
||||
- Azul Zulu 8 JRE（可选 ZuluFX 含 JavaFX）：[下载页面](https://www.azul.com/downloads/?version=java-8-lts&package=jre)
|
||||
- BellSoft Liberica 8 JRE（Standard/Full，Full 含 JavaFX）：[下载页面](https://bell-sw.com/pages/downloads/#/java-8-lts)
|
||||
- Eclipse Temurin 8 JRE（Adoptium）：[下载页面](https://adoptium.net/temurin/releases/?version=8)
|
||||
|
||||
选择要点：
|
||||
- 需要 AWT/Swing/字体/打印 → 选择非 headless 包。
|
||||
- 需要 JavaFX → 选择 Liberica Full 或 ZuluFX。
|
||||
- 仅命令行/服务端 → 任意 JRE 8（headless 也可）。
|
||||
|
||||
### 目录放置约定
|
||||
将解压后的 JRE 放入项目的 `build/extraResources/jre`，保证内部存在 `bin/java(.exe)`：
|
||||
|
||||
```
|
||||
build/
|
||||
extraResources/
|
||||
jre/
|
||||
bin/
|
||||
java(.exe)
|
||||
lib/
|
||||
...
|
||||
```
|
||||
|
||||
构建后在生产环境可通过 `process.resourcesPath` 访问：
|
||||
`<app>/resources/extraResources/jre/bin/java(.exe)`。
|
||||
|
||||
### 主进程调用示例
|
||||
在 `electron/preload/lifecycle.js` 或你的业务模块中封装 Java 运行工具（开发/生产两种路径）：
|
||||
|
||||
```js
|
||||
const path = require('path');
|
||||
const { spawn } = require('child_process');
|
||||
|
||||
function getExtraResourcesDir() {
|
||||
// 开发态：使用项目目录；生产态：使用 asar/resources 目录
|
||||
const isDev = !!process.env.EE_DEV || process.env.NODE_ENV === 'development';
|
||||
return isDev
|
||||
? path.join(process.cwd(), 'build', 'extraResources')
|
||||
: path.join(process.resourcesPath, 'extraResources');
|
||||
}
|
||||
|
||||
function getJavaBinPath() {
|
||||
const extraDir = getExtraResourcesDir();
|
||||
const javaBinName = process.platform === 'win32' ? 'java.exe' : 'java';
|
||||
return path.join(extraDir, 'jre', 'bin', javaBinName);
|
||||
}
|
||||
|
||||
function runJavaJar(jarAbsPath, args = [], options = {}) {
|
||||
const javaPath = getJavaBinPath();
|
||||
const child = spawn(javaPath, ['-jar', jarAbsPath, ...args], {
|
||||
stdio: 'inherit',
|
||||
...options,
|
||||
});
|
||||
return child;
|
||||
}
|
||||
|
||||
async function ensureJavaVersion(logger) {
|
||||
return new Promise((resolve) => {
|
||||
const child = spawn(getJavaBinPath(), ['-version']);
|
||||
let out = '';
|
||||
let err = '';
|
||||
child.stdout && child.stdout.on('data', (d) => (out += d.toString()))
|
||||
child.stderr && child.stderr.on('data', (d) => (err += d.toString()))
|
||||
child.on('close', () => {
|
||||
const text = (out + '\n' + err).trim();
|
||||
logger && logger.info('[java] version check:', text);
|
||||
resolve(text.includes('1.8.0'));
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
module.exports = { getJavaBinPath, runJavaJar, ensureJavaVersion };
|
||||
```
|
||||
|
||||
在生命周期中调用（示例）：
|
||||
|
||||
```js
|
||||
const { logger } = require('ee-core/log');
|
||||
const path = require('path');
|
||||
const { runJavaJar, ensureJavaVersion } = require('./java-runner');
|
||||
|
||||
class Lifecycle {
|
||||
async ready() {
|
||||
const ok = await ensureJavaVersion(logger);
|
||||
if (!ok) {
|
||||
logger.error('[java] 未检测到 JRE 8，请检查 extraResources/jre 是否存在');
|
||||
}
|
||||
}
|
||||
|
||||
async windowReady() {
|
||||
const jarPath = path.join(process.resourcesPath || process.cwd(), 'extraResources', 'tools', 'your-app.jar');
|
||||
// 示例：延后在某业务时机再启动 Java 进程
|
||||
// const proc = runJavaJar(jarPath, ['--arg1', 'value']);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
注意：示例中的 `java-runner` 为上文工具函数文件，实际请按你的项目结构放置。
|
||||
|
||||
### 验证清单
|
||||
- 运行 `jre/bin/java -version` 输出包含 `1.8.0_xxx`。
|
||||
- 若涉及 GUI/字体/打印，验证 AWT/Swing 中文渲染与打印。
|
||||
- 若需 JavaFX，验证 JavaFX Demo 启动。
|
||||
- 若涉及 TLS/HTTPS，验证 SSL 通信正常。
|
||||
|
||||
### 许可与合规
|
||||
- Azul Zulu、Eclipse Temurin（Adoptium）、BellSoft Liberica 的 JRE/JDK 8 发行包均可免费再分发（GPLv2+CE 或厂商许可证）。
|
||||
- 建议在应用的“关于/许可证”中附上所选发行版的许可证链接与致谢。
|
||||
|
||||
### 常见问题
|
||||
1) 是否“阉割”？
|
||||
— 上述 JRE 8 发行版均为标准运行时，通过兼容性测试；JRE 不包含开发者工具属于正常区别，不是删减。
|
||||
|
||||
2) 何时需要 JDK 而不是 JRE？
|
||||
— 需要 `javac` 编译或 `jcmd/jmap` 等诊断工具，或你的 Java 组件依赖 `tools.jar` 时。
|
||||
|
||||
3) 体积如何优化？
|
||||
— 选择 headless（若无 GUI 需求）、去除无用语言/字体包；或改用 JDK 9+ 使用 jlink（不适用于 8）。
|
||||
|
||||
|
||||
436
doc/打包方案对比.md
Normal file
436
doc/打包方案对比.md
Normal file
@@ -0,0 +1,436 @@
|
||||
# 应用打包方案对比与实现
|
||||
|
||||
本文档详细说明 ElectronEgg 应用的两种打包方案：纯绿色版方案 和 双版本方案。
|
||||
|
||||
---
|
||||
|
||||
## 方案对比
|
||||
|
||||
| 特性 | 方案一：纯绿色版 | 方案二：双版本打包 |
|
||||
|------|-----------------|-------------------|
|
||||
| **打包产物** | 单个便携版 exe | 安装版 exe + 便携版 exe |
|
||||
| **安装过程** | 无需安装 | 安装版需安装，便携版无需 |
|
||||
| **桌面快捷方式** | 应用内自动创建 | 安装版自动创建，便携版手动或自动 |
|
||||
| **开始菜单** | 无 | 安装版有 |
|
||||
| **卸载程序** | 无（直接删除） | 安装版有 |
|
||||
| **适用场景** | 临时使用、U盘携带 | 正式部署、企业分发 |
|
||||
| **用户体验** | 灵活、轻量 | 专业、完整 |
|
||||
| **打包时间** | 快 | 较慢（打包两次） |
|
||||
| **分发复杂度** | 简单（单文件） | 中等（两个文件） |
|
||||
|
||||
---
|
||||
|
||||
## 方案一：纯绿色版 + 自动创建快捷方式
|
||||
|
||||
### 特点
|
||||
- ✅ 单个 exe 文件，双击即用
|
||||
- ✅ 首次启动时询问是否创建桌面快捷方式
|
||||
- ✅ 无需安装，无需卸载
|
||||
- ✅ 适合快速分发和临时使用
|
||||
|
||||
### 实现步骤
|
||||
|
||||
#### 1. 修改打包配置
|
||||
|
||||
**文件**：[cmd/builder.json](../cmd/builder.json)
|
||||
|
||||
```json
|
||||
{
|
||||
"productName": "南京灿能工具",
|
||||
"appId": "com.canneng.tool",
|
||||
"copyright": "© 2025 hongawen",
|
||||
"directories": {
|
||||
"output": "out"
|
||||
},
|
||||
"asar": true,
|
||||
"files": [
|
||||
"**/*",
|
||||
"!cmd/",
|
||||
"!data/",
|
||||
"!electron/",
|
||||
"!frontend/",
|
||||
"!logs/",
|
||||
"!out/",
|
||||
"!go/",
|
||||
"!python/"
|
||||
],
|
||||
"extraResources": {
|
||||
"from": "build/extraResources/",
|
||||
"to": "extraResources"
|
||||
},
|
||||
"publish": [
|
||||
{
|
||||
"provider": "generic",
|
||||
"url": "https://your-update-server.com"
|
||||
}
|
||||
],
|
||||
"win": {
|
||||
"icon": "build/icons/icon.ico",
|
||||
"artifactName": "${productName}-${os}-${version}-${arch}.${ext}",
|
||||
"target": [
|
||||
{
|
||||
"target": "portable"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. 添加自动创建快捷方式功能
|
||||
|
||||
**文件**：[electron/preload/lifecycle.js](../electron/preload/lifecycle.js)
|
||||
|
||||
在 `windowReady()` 钩子中添加以下代码：
|
||||
|
||||
```javascript
|
||||
const { logger } = require('ee-core/log');
|
||||
const { getConfig } = require('ee-core/config');
|
||||
const { getMainWindow } = require('ee-core/electron');
|
||||
|
||||
class Lifecycle {
|
||||
|
||||
async ready() {
|
||||
logger.info('[lifecycle] ready');
|
||||
}
|
||||
|
||||
async electronAppReady() {
|
||||
logger.info('[lifecycle] electron-app-ready');
|
||||
}
|
||||
|
||||
async windowReady() {
|
||||
logger.info('[lifecycle] window-ready');
|
||||
|
||||
// 延迟加载，无白屏
|
||||
const { windowsOption } = getConfig();
|
||||
if (windowsOption.show == false) {
|
||||
const win = getMainWindow();
|
||||
win.once('ready-to-show', () => {
|
||||
win.show();
|
||||
win.focus();
|
||||
})
|
||||
}
|
||||
|
||||
// 绿色版自动创建桌面快捷方式
|
||||
await this.createDesktopShortcut();
|
||||
}
|
||||
|
||||
/**
|
||||
* 为绿色版创建桌面快捷方式
|
||||
*/
|
||||
async createDesktopShortcut() {
|
||||
const { app, dialog, shell } = require('electron');
|
||||
const path = require('path');
|
||||
const fs = require('fs');
|
||||
|
||||
// 判断是否为便携版（绿色版）
|
||||
// 安装版通常在 C:\Program Files 或 AppData\Local\Programs
|
||||
const isPortable = process.platform === 'win32' &&
|
||||
!process.execPath.includes('Program Files') &&
|
||||
!process.execPath.includes('AppData\\Local\\Programs');
|
||||
|
||||
if (!isPortable) {
|
||||
logger.info('[lifecycle] 非便携版，跳过快捷方式创建');
|
||||
return;
|
||||
}
|
||||
|
||||
try {
|
||||
const desktopPath = app.getPath('desktop');
|
||||
const shortcutPath = path.join(desktopPath, '南京灿能工具.lnk');
|
||||
|
||||
// 如果快捷方式已存在，跳过
|
||||
if (fs.existsSync(shortcutPath)) {
|
||||
logger.info('[lifecycle] 桌面快捷方式已存在');
|
||||
return;
|
||||
}
|
||||
|
||||
// 询问用户是否创建快捷方式
|
||||
const result = await dialog.showMessageBox({
|
||||
type: 'question',
|
||||
buttons: ['创建', '跳过'],
|
||||
defaultId: 0,
|
||||
title: '创建桌面快捷方式',
|
||||
message: '是否在桌面创建快捷方式？',
|
||||
detail: '方便您下次快速启动应用'
|
||||
});
|
||||
|
||||
if (result.response === 0) {
|
||||
// Windows 下创建快捷方式
|
||||
const success = shell.writeShortcutLink(shortcutPath, {
|
||||
target: process.execPath,
|
||||
cwd: path.dirname(process.execPath),
|
||||
description: '南京灿能C端工具',
|
||||
icon: process.execPath,
|
||||
iconIndex: 0
|
||||
});
|
||||
|
||||
if (success) {
|
||||
logger.info('[lifecycle] 桌面快捷方式创建成功');
|
||||
await dialog.showMessageBox({
|
||||
type: 'info',
|
||||
title: '成功',
|
||||
message: '桌面快捷方式已创建',
|
||||
buttons: ['确定']
|
||||
});
|
||||
} else {
|
||||
logger.error('[lifecycle] 桌面快捷方式创建失败');
|
||||
}
|
||||
} else {
|
||||
logger.info('[lifecycle] 用户跳过创建快捷方式');
|
||||
}
|
||||
} catch (error) {
|
||||
logger.error('[lifecycle] 创建快捷方式时出错:', error);
|
||||
}
|
||||
}
|
||||
|
||||
async beforeClose() {
|
||||
logger.info('[lifecycle] before-close');
|
||||
}
|
||||
}
|
||||
Lifecycle.toString = () => '[class Lifecycle]';
|
||||
|
||||
module.exports = {
|
||||
Lifecycle
|
||||
};
|
||||
```
|
||||
|
||||
#### 3. 打包命令
|
||||
|
||||
```bash
|
||||
npm run build # 完整构建
|
||||
npm run build-w # 打包 Windows 便携版
|
||||
```
|
||||
|
||||
#### 4. 产物说明
|
||||
|
||||
打包完成后，在 `out/` 目录下会生成：
|
||||
```
|
||||
out/
|
||||
└── 南京灿能工具-win-4.0.0-x64.exe （便携版，约 150-200MB）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 方案二：双版本打包（安装版 + 便携版）
|
||||
|
||||
### 特点
|
||||
- ✅ 提供两种版本供用户选择
|
||||
- ✅ 安装版：专业、完整的安装体验
|
||||
- ✅ 便携版：灵活、轻量，无需安装
|
||||
- ✅ 适合正式产品发布
|
||||
|
||||
### 实现步骤
|
||||
|
||||
#### 1. 修改打包配置
|
||||
|
||||
**文件**：[cmd/builder.json](../cmd/builder.json)
|
||||
|
||||
```json
|
||||
{
|
||||
"productName": "南京灿能工具",
|
||||
"appId": "com.canneng.tool",
|
||||
"copyright": "© 2025 hongawen",
|
||||
"directories": {
|
||||
"output": "out"
|
||||
},
|
||||
"asar": true,
|
||||
"files": [
|
||||
"**/*",
|
||||
"!cmd/",
|
||||
"!data/",
|
||||
"!electron/",
|
||||
"!frontend/",
|
||||
"!logs/",
|
||||
"!out/",
|
||||
"!go/",
|
||||
"!python/"
|
||||
],
|
||||
"extraResources": {
|
||||
"from": "build/extraResources/",
|
||||
"to": "extraResources"
|
||||
},
|
||||
"nsis": {
|
||||
"oneClick": false,
|
||||
"allowElevation": true,
|
||||
"allowToChangeInstallationDirectory": true,
|
||||
"installerIcon": "build/icons/icon.ico",
|
||||
"uninstallerIcon": "build/icons/icon.ico",
|
||||
"installerHeaderIcon": "build/icons/icon.ico",
|
||||
"createDesktopShortcut": true,
|
||||
"createStartMenuShortcut": true,
|
||||
"shortcutName": "南京灿能工具",
|
||||
"artifactName": "${productName}-Setup-${version}.${ext}"
|
||||
},
|
||||
"portable": {
|
||||
"artifactName": "${productName}-Portable-${version}.${ext}"
|
||||
},
|
||||
"publish": [
|
||||
{
|
||||
"provider": "generic",
|
||||
"url": "https://your-update-server.com"
|
||||
}
|
||||
],
|
||||
"win": {
|
||||
"icon": "build/icons/icon.ico",
|
||||
"target": [
|
||||
{
|
||||
"target": "nsis",
|
||||
"arch": ["x64"]
|
||||
},
|
||||
{
|
||||
"target": "portable",
|
||||
"arch": ["x64"]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. 便携版快捷方式功能（可选）
|
||||
|
||||
如果希望便携版也能自动创建快捷方式，使用**方案一**中的 `createDesktopShortcut()` 代码。
|
||||
|
||||
#### 3. 打包命令
|
||||
|
||||
```bash
|
||||
npm run build # 完整构建
|
||||
npm run build-w # 打包两个版本
|
||||
```
|
||||
|
||||
#### 4. 产物说明
|
||||
|
||||
打包完成后，在 `out/` 目录下会生成：
|
||||
```
|
||||
out/
|
||||
├── 南京灿能工具-Setup-4.0.0.exe （安装版，约 150MB）
|
||||
└── 南京灿能工具-Portable-4.0.0.exe （便携版，约 150-200MB）
|
||||
```
|
||||
|
||||
#### 5. 版本差异说明
|
||||
|
||||
**安装版 (NSIS)**：
|
||||
- 需要安装到系统（默认 C:\Program Files）
|
||||
- 自动创建桌面快捷方式
|
||||
- 自动创建开始菜单项
|
||||
- 提供卸载程序
|
||||
- 支持自动更新
|
||||
- 适合企业部署、长期使用
|
||||
|
||||
**便携版 (Portable)**：
|
||||
- 单个 exe 文件
|
||||
- 双击直接运行（首次会自解压）
|
||||
- 无需安装，无需卸载
|
||||
- 可放在 U 盘随身携带
|
||||
- 适合临时使用、测试环境
|
||||
|
||||
---
|
||||
|
||||
## 快捷方式创建原理（技术细节）
|
||||
|
||||
### Windows 快捷方式 (.lnk)
|
||||
|
||||
```javascript
|
||||
shell.writeShortcutLink(shortcutPath, {
|
||||
target: process.execPath, // 目标程序路径
|
||||
cwd: path.dirname(process.execPath), // 工作目录
|
||||
description: '应用描述', // 快捷方式描述
|
||||
icon: process.execPath, // 图标路径
|
||||
iconIndex: 0, // 图标索引
|
||||
args: '', // 启动参数（可选）
|
||||
appUserModelId: 'com.app.id' // Windows 应用 ID（可选）
|
||||
})
|
||||
```
|
||||
|
||||
### 判断是否为便携版
|
||||
|
||||
```javascript
|
||||
const isPortable = process.platform === 'win32' &&
|
||||
!process.execPath.includes('Program Files') &&
|
||||
!process.execPath.includes('AppData\\Local\\Programs');
|
||||
```
|
||||
|
||||
**原理**：
|
||||
- 安装版通常安装在 `C:\Program Files\YourApp\`
|
||||
- 或者 `C:\Users\用户名\AppData\Local\Programs\YourApp\`
|
||||
- 便携版可以在任意位置运行
|
||||
|
||||
---
|
||||
|
||||
## 推荐配置
|
||||
|
||||
### 企业级应用（推荐方案二）
|
||||
```
|
||||
✅ 提供两个版本
|
||||
✅ 主推安装版（专业形象）
|
||||
✅ 提供便携版作为备选
|
||||
```
|
||||
|
||||
### 轻量工具（推荐方案一）
|
||||
```
|
||||
✅ 只提供便携版
|
||||
✅ 应用内自动创建快捷方式
|
||||
✅ 简化分发流程
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q1: 便携版首次启动为什么慢？
|
||||
**A**: 便携版是自解压程序，首次运行需要解压资源到临时目录（约 3-5 秒）。后续启动会快很多。
|
||||
|
||||
### Q2: 便携版数据存储在哪里？
|
||||
**A**:
|
||||
- 用户数据：`C:\Users\用户名\AppData\Roaming\你的appId\`
|
||||
- 临时文件：`C:\Users\用户名\AppData\Local\Temp\`
|
||||
|
||||
### Q3: 如何让便携版也支持自动更新？
|
||||
**A**: 需要配置 `electron-updater`，但便携版更新体验不如安装版。建议：
|
||||
- 安装版：使用自动更新
|
||||
- 便携版：提示用户下载新版本
|
||||
|
||||
### Q4: 可以同时运行两个版本吗？
|
||||
**A**: 不建议。虽然技术上可行，但会导致数据冲突（共享同一个 userData 目录）。
|
||||
|
||||
### Q5: 如何自定义快捷方式图标？
|
||||
**A**: 在 `build/icons/` 目录放置 `.ico` 文件，并在 `builder.json` 中配置：
|
||||
```json
|
||||
"win": {
|
||||
"icon": "build/icons/custom-icon.ico"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 测试检查清单
|
||||
|
||||
打包完成后，请进行以下测试：
|
||||
|
||||
### 安装版测试
|
||||
- [ ] 安装到默认路径成功
|
||||
- [ ] 安装到自定义路径成功
|
||||
- [ ] 桌面快捷方式正常
|
||||
- [ ] 开始菜单项正常
|
||||
- [ ] 应用启动正常
|
||||
- [ ] 卸载程序正常
|
||||
|
||||
### 便携版测试
|
||||
- [ ] 双击 exe 正常启动
|
||||
- [ ] 首次启动自动创建快捷方式（如已实现）
|
||||
- [ ] 桌面快捷方式可用
|
||||
- [ ] 应用功能正常
|
||||
- [ ] 关闭后再次启动正常
|
||||
- [ ] 可移动到其他目录运行
|
||||
|
||||
---
|
||||
|
||||
## 参考资源
|
||||
|
||||
- electron-builder 官方文档: https://www.electron.build/
|
||||
- NSIS 配置: https://www.electron.build/configuration/nsis
|
||||
- Portable 配置: https://www.electron.build/configuration/portable
|
||||
- Electron shell API: https://www.electronjs.org/docs/latest/api/shell
|
||||
|
||||
---
|
||||
|
||||
*文档创建时间: 2025-10-14*
|
||||
*作者: hongawen*
|
||||
459
doc/生命周期描述.md
Normal file
459
doc/生命周期描述.md
Normal file
@@ -0,0 +1,459 @@
|
||||
# ElectronEgg 生命周期详解
|
||||
|
||||
本文档详细说明 ElectronEgg 框架的应用生命周期机制及其在项目中的实现。
|
||||
|
||||
## 生命周期流程图
|
||||
|
||||
```
|
||||
┌─────────────┐
|
||||
│ new │ 创建 ElectronEgg 实例
|
||||
└──────┬──────┘
|
||||
│
|
||||
┌──────▼──────┐
|
||||
│ ready │ core app 加载完成（ee-core 框架初始化）
|
||||
└──────┬──────┘
|
||||
│
|
||||
┌──────▼─────────────┐
|
||||
│ electronAppReady │ Electron app 加载完成
|
||||
└──────┬─────────────┘
|
||||
│
|
||||
├─────────────────┐
|
||||
│ │
|
||||
┌──────▼──────┐ ┌─────▼────────┐
|
||||
│ mainWindow │ │ windowReady │ 主窗口创建完成
|
||||
└──────┬──────┘ └─────▲────────┘
|
||||
│ │
|
||||
└─────────────────┘
|
||||
│
|
||||
┌──────▼──────┐
|
||||
│ running │ 应用运行中
|
||||
└──────┬──────┘
|
||||
│
|
||||
┌──────▼──────┐
|
||||
│beforeClose │ 退出之前触发
|
||||
└──────┬──────┘
|
||||
│
|
||||
┌──────▼──────┐
|
||||
│ quit │ 应用退出
|
||||
└─────────────┘
|
||||
```
|
||||
|
||||
## 生命周期钩子详解
|
||||
|
||||
### 1. new - 实例创建
|
||||
|
||||
**触发时机**：调用 `new ElectronEgg()` 时
|
||||
|
||||
**实现位置**：[electron/main.js](electron/main.js#L6)
|
||||
|
||||
```javascript
|
||||
const { ElectronEgg } = require('ee-core');
|
||||
const app = new ElectronEgg();
|
||||
```
|
||||
|
||||
**作用**：
|
||||
- 创建 ElectronEgg 应用实例
|
||||
- 初始化框架核心模块
|
||||
- 准备生命周期管理器
|
||||
|
||||
---
|
||||
|
||||
### 2. ready - 核心应用就绪
|
||||
|
||||
**触发时机**：ee-core 框架加载完成，Electron app 启动之前
|
||||
|
||||
**实现位置**：
|
||||
- 注册：[electron/main.js](electron/main.js#L10)
|
||||
- 实现：[electron/preload/lifecycle.js](electron/preload/lifecycle.js#L12-L14)
|
||||
|
||||
```javascript
|
||||
// 注册
|
||||
app.register("ready", life.ready);
|
||||
|
||||
// 实现
|
||||
async ready() {
|
||||
logger.info('[lifecycle] ready');
|
||||
// 在这里可以做：
|
||||
// - 初始化数据库连接
|
||||
// - 加载配置文件
|
||||
// - 初始化全局变量
|
||||
}
|
||||
```
|
||||
|
||||
**适用场景**：
|
||||
- ✅ 初始化数据库连接
|
||||
- ✅ 加载应用配置
|
||||
- ✅ 注册全局服务
|
||||
- ✅ 初始化日志系统
|
||||
- ❌ 不能操作窗口（窗口还未创建）
|
||||
|
||||
---
|
||||
|
||||
### 3. electronAppReady - Electron 应用就绪
|
||||
|
||||
**触发时机**：Electron 的 `app.ready` 事件触发后，主窗口创建之前
|
||||
|
||||
**实现位置**：
|
||||
- 注册：[electron/main.js](electron/main.js#L11)
|
||||
- 实现：[electron/preload/lifecycle.js](electron/preload/lifecycle.js#L19-L21)
|
||||
|
||||
```javascript
|
||||
// 注册
|
||||
app.register("electron-app-ready", life.electronAppReady);
|
||||
|
||||
// 实现
|
||||
async electronAppReady() {
|
||||
logger.info('[lifecycle] electron-app-ready');
|
||||
// 在这里可以做：
|
||||
// - 注册全局快捷键
|
||||
// - 设置应用菜单
|
||||
// - 初始化托盘图标
|
||||
// - 注册协议处理
|
||||
}
|
||||
```
|
||||
|
||||
**适用场景**：
|
||||
- ✅ 注册全局快捷键 (globalShortcut)
|
||||
- ✅ 创建应用菜单 (Menu)
|
||||
- ✅ 创建系统托盘 (Tray)
|
||||
- ✅ 注册自定义协议 (protocol)
|
||||
- ⚠️ 可以创建窗口，但通常在框架内部自动创建
|
||||
|
||||
---
|
||||
|
||||
### 4. mainWindow - 主窗口创建
|
||||
|
||||
**触发时机**：框架创建主窗口时（内部流程，不需要手动注册）
|
||||
|
||||
**说明**：
|
||||
- 这是框架内部自动执行的步骤
|
||||
- 根据 `electron/config/config.*.js` 中的 `windowsOption` 配置创建窗口
|
||||
- 窗口创建完成后会触发 `windowReady` 钩子
|
||||
|
||||
**配置示例**：
|
||||
```javascript
|
||||
// electron/config/config.default.js
|
||||
windowsOption: {
|
||||
width: 1200,
|
||||
height: 800,
|
||||
show: false, // 设置为 false 可实现无白屏启动
|
||||
webPreferences: {
|
||||
contextIsolation: false,
|
||||
nodeIntegration: true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. windowReady - 窗口就绪
|
||||
|
||||
**触发时机**：主窗口创建完成，页面加载完毕
|
||||
|
||||
**实现位置**：
|
||||
- 注册：[electron/main.js](electron/main.js#L12)
|
||||
- 实现：[electron/preload/lifecycle.js](electron/preload/lifecycle.js#L26-L37)
|
||||
|
||||
```javascript
|
||||
// 注册
|
||||
app.register("window-ready", life.windowReady);
|
||||
|
||||
// 实现
|
||||
async windowReady() {
|
||||
logger.info('[lifecycle] window-ready');
|
||||
|
||||
// 延迟显示窗口，避免白屏
|
||||
const { windowsOption } = getConfig();
|
||||
if (windowsOption.show == false) {
|
||||
const win = getMainWindow();
|
||||
win.once('ready-to-show', () => {
|
||||
win.show(); // 显示窗口
|
||||
win.focus(); // 聚焦窗口
|
||||
})
|
||||
}
|
||||
|
||||
// 在这里可以做：
|
||||
// - 向渲染进程发送初始化数据
|
||||
// - 检查更新
|
||||
// - 加载用户配置
|
||||
}
|
||||
```
|
||||
|
||||
**适用场景**：
|
||||
- ✅ 操作主窗口 (show/hide/maximize 等)
|
||||
- ✅ 向渲染进程发送消息
|
||||
- ✅ 执行自动更新检查
|
||||
- ✅ 加载用户数据并同步到前端
|
||||
- ✅ 实现无白屏启动（配合 `show: false`）
|
||||
|
||||
---
|
||||
|
||||
### 6. running - 应用运行中
|
||||
|
||||
**触发时机**：窗口显示后，应用正常运行期间
|
||||
|
||||
**说明**：
|
||||
- 这不是一个独立的生命周期钩子
|
||||
- 表示应用的正常运行状态
|
||||
- 此时所有功能都可用
|
||||
|
||||
**可用操作**：
|
||||
- IPC 通信（前后端交互）
|
||||
- 业务逻辑处理
|
||||
- 数据库操作
|
||||
- 网络请求
|
||||
- 文件系统操作
|
||||
|
||||
---
|
||||
|
||||
### 7. beforeClose - 关闭前钩子
|
||||
|
||||
**触发时机**：用户点击关闭按钮或调用 `app.quit()` 之前
|
||||
|
||||
**实现位置**：
|
||||
- 注册：[electron/main.js](electron/main.js#L13)
|
||||
- 实现：[electron/preload/lifecycle.js](electron/preload/lifecycle.js#L42-L44)
|
||||
|
||||
```javascript
|
||||
// 注册
|
||||
app.register("before-close", life.beforeClose);
|
||||
|
||||
// 实现
|
||||
async beforeClose() {
|
||||
logger.info('[lifecycle] before-close');
|
||||
// 在这里可以做：
|
||||
// - 保存用户数据
|
||||
// - 关闭数据库连接
|
||||
// - 清理临时文件
|
||||
// - 释放系统资源
|
||||
// - 确认是否退出
|
||||
}
|
||||
```
|
||||
|
||||
**适用场景**：
|
||||
- ✅ 保存应用状态
|
||||
- ✅ 关闭数据库连接
|
||||
- ✅ 清理临时资源
|
||||
- ✅ 询问用户是否确认退出
|
||||
- ✅ 上传日志或统计数据
|
||||
|
||||
**阻止关闭示例**：
|
||||
```javascript
|
||||
async beforeClose(args, event) {
|
||||
const { dialog } = require('electron');
|
||||
const result = await dialog.showMessageBox({
|
||||
type: 'question',
|
||||
buttons: ['取消', '退出'],
|
||||
message: '确定要退出应用吗？'
|
||||
});
|
||||
|
||||
if (result.response === 0) {
|
||||
// 阻止关闭
|
||||
return false;
|
||||
}
|
||||
|
||||
// 允许关闭
|
||||
return true;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 8. quit - 应用退出
|
||||
|
||||
**触发时机**：`beforeClose` 完成后，应用进程终止
|
||||
|
||||
**说明**：
|
||||
- 这是最终状态，不可逆
|
||||
- 所有资源清理应在 `beforeClose` 中完成
|
||||
- 退出后进程结束，无法执行代码
|
||||
|
||||
---
|
||||
|
||||
## 额外生命周期：preload
|
||||
|
||||
### preload - 预加载模块
|
||||
|
||||
**触发时机**：应用启动时，在所有其他钩子之前
|
||||
|
||||
**实现位置**：
|
||||
- 注册：[electron/main.js](electron/main.js#L16)
|
||||
- 实现：[electron/preload/index.js](electron/preload/index.js#L7-L9)
|
||||
|
||||
```javascript
|
||||
// 注册
|
||||
app.register("preload", preload);
|
||||
|
||||
// 实现
|
||||
function preload() {
|
||||
logger.info('[preload] load 1');
|
||||
// 在这里可以做：
|
||||
// - 加载环境变量
|
||||
// - 注册原生模块
|
||||
// - 设置全局异常处理
|
||||
}
|
||||
```
|
||||
|
||||
**适用场景**：
|
||||
- ✅ 加载环境变量
|
||||
- ✅ 注册 Node.js 原生模块
|
||||
- ✅ 设置全局错误处理
|
||||
- ✅ 初始化第三方 SDK
|
||||
|
||||
---
|
||||
|
||||
## 实际开发示例
|
||||
|
||||
### 示例 1：数据库初始化
|
||||
|
||||
```javascript
|
||||
// electron/preload/lifecycle.js
|
||||
const Database = require('better-sqlite3');
|
||||
let db;
|
||||
|
||||
class Lifecycle {
|
||||
async ready() {
|
||||
// 在 ready 钩子中初始化数据库
|
||||
const path = require('path');
|
||||
const dbPath = path.join(app.getPath('userData'), 'app.db');
|
||||
db = new Database(dbPath);
|
||||
logger.info('[lifecycle] database initialized');
|
||||
}
|
||||
|
||||
async beforeClose() {
|
||||
// 在关闭前关闭数据库连接
|
||||
if (db) {
|
||||
db.close();
|
||||
logger.info('[lifecycle] database closed');
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 示例 2：自动更新检查
|
||||
|
||||
```javascript
|
||||
// electron/preload/lifecycle.js
|
||||
const { autoUpdater } = require('electron-updater');
|
||||
|
||||
class Lifecycle {
|
||||
async windowReady() {
|
||||
// 窗口就绪后检查更新
|
||||
const { getMainWindow } = require('ee-core/electron');
|
||||
const win = getMainWindow();
|
||||
|
||||
autoUpdater.checkForUpdates();
|
||||
|
||||
autoUpdater.on('update-available', () => {
|
||||
win.webContents.send('update-available');
|
||||
});
|
||||
|
||||
logger.info('[lifecycle] update check started');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 示例 3：托盘图标
|
||||
|
||||
```javascript
|
||||
// electron/preload/lifecycle.js
|
||||
const { Tray, Menu } = require('electron');
|
||||
let tray;
|
||||
|
||||
class Lifecycle {
|
||||
async electronAppReady() {
|
||||
// 在 Electron 就绪后创建托盘
|
||||
const path = require('path');
|
||||
const iconPath = path.join(__dirname, '../../public/images/tray-icon.png');
|
||||
|
||||
tray = new Tray(iconPath);
|
||||
const contextMenu = Menu.buildFromTemplate([
|
||||
{ label: '打开主窗口', click: () => {
|
||||
const { getMainWindow } = require('ee-core/electron');
|
||||
getMainWindow().show();
|
||||
}},
|
||||
{ label: '退出', click: () => {
|
||||
const { app } = require('electron');
|
||||
app.quit();
|
||||
}}
|
||||
]);
|
||||
|
||||
tray.setContextMenu(contextMenu);
|
||||
logger.info('[lifecycle] tray created');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 示例 4：无白屏启动
|
||||
|
||||
```javascript
|
||||
// electron/config/config.default.js
|
||||
windowsOption: {
|
||||
width: 1200,
|
||||
height: 800,
|
||||
show: false, // 关键配置：初始不显示
|
||||
backgroundColor: '#ffffff'
|
||||
}
|
||||
|
||||
// electron/preload/lifecycle.js
|
||||
class Lifecycle {
|
||||
async windowReady() {
|
||||
// 页面加载完成后再显示，避免白屏
|
||||
const { getMainWindow } = require('ee-core/electron');
|
||||
const win = getMainWindow();
|
||||
|
||||
win.once('ready-to-show', () => {
|
||||
win.show();
|
||||
win.focus();
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 生命周期执行顺序总结
|
||||
|
||||
```
|
||||
1. preload() # 预加载模块
|
||||
2. new ElectronEgg() # 创建应用实例
|
||||
3. ready() # 核心框架就绪
|
||||
4. electronAppReady() # Electron 就绪
|
||||
5. [创建主窗口] # 框架内部创建窗口
|
||||
6. windowReady() # 窗口就绪
|
||||
7. [应用运行中] # 正常运行状态
|
||||
8. beforeClose() # 关闭前钩子
|
||||
9. [应用退出] # 进程结束
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **异步支持**：所有生命周期钩子都支持 `async/await`，可以执行异步操作
|
||||
|
||||
2. **错误处理**：建议在每个钩子中添加 try-catch 错误处理
|
||||
|
||||
3. **顺序依赖**：不要在早期钩子中访问尚未初始化的资源（如在 `ready` 中操作窗口）
|
||||
|
||||
4. **性能优化**：避免在钩子中执行耗时操作，会阻塞应用启动
|
||||
|
||||
5. **资源清理**：在 `beforeClose` 中务必清理所有资源，避免内存泄漏
|
||||
|
||||
6. **日志记录**：建议在每个钩子中记录日志，方便排查问题
|
||||
|
||||
---
|
||||
|
||||
## 相关文件
|
||||
|
||||
- 生命周期注册：[electron/main.js](electron/main.js)
|
||||
- 生命周期实现：[electron/preload/lifecycle.js](electron/preload/lifecycle.js)
|
||||
- 预加载模块：[electron/preload/index.js](electron/preload/index.js)
|
||||
- 窗口配置：[electron/config/config.default.js](electron/config/config.default.js)
|
||||
|
||||
---
|
||||
|
||||
## 参考资源
|
||||
|
||||
- ElectronEgg 官方文档：https://www.kaka996.com/pages/987b1c/
|
||||
- Electron 官方文档：https://www.electronjs.org/zh/docs/latest/
|
||||
Reference in New Issue
Block a user