@hmos-library-adapter/fast 0.0.17-beta.0 → 0.0.17-beta.2

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/electron/guides/electron-builder-packaging-internals.md

@@ -0,0 +1,723 @@
+# electron-builder 打包 macOS App 原理深度解析
+
+---
+
+## 一、前置知识：macOS .app 包结构
+
+macOS 应用并非单个可执行文件，而是一个**目录树**，扩展名为 `.app`，Finder 会将其显示为单个图标。这个目录遵循 Apple 的 **Bundle Structure** 规范：
+
+```
+MyApp.app/
+└── Contents/
+    ├── Info.plist          # 应用元数据（名称、版本、权限声明等）
+    ├── PkgInfo             # 8 字节类型签名（APPL????）
+    ├── MacOS/
+    │   └── MyApp           # 主可执行文件（Mach-O 格式）
+    ├── Frameworks/         # 嵌入的动态库和辅助程序
+    │   ├── MyApp Helper.app/
+    │   └── SomeLib.framework/
+    ├── Resources/          # 资源文件（图标、nib、本地化等）
+    │   ├── MyApp.icns
+    │   ├── en.lproj/
+    │   └── zh_CN.lproj/
+    ├── PlugIns/            # 可选插件
+    ├── XPCServices/        # 可选 XPC 服务
+    ├── _CodeSignature/     # 代码签名
+    │   └── CodeResources
+    └── embedded.provisionprofile  # 可选，沙箱配置
+```
+
+**关键规则**：
+
+- `Info.plist` 中 `CFBundleExecutable` 的值必须与 `MacOS/` 下可执行文件名一致
+- `CFBundleIdentifier` 是应用的唯一标识（反向域名格式，如 `com.example.myapp`）
+- `Frameworks/` 中的 Helper.app 也是完整的 .app 包，有自己的 Info.plist
+- macOS Launch Services 通过读取 Info.plist 注册应用
+
+---
+
+## 二、electron-builder 的输入与输出
+
+### 输入
+
+```
+你的工程/
+├── package.json          # 含 build 配置、name、version、main
+├── main.js               # 主进程代码
+├── preload.js            # 预加载脚本
+├── index.html            # 渲染页面
+└── node_modules/         # 依赖
+```
+
+### 输出
+
+```
+dist/
+├── mac-arm64/
+│   └── HelloElectron.app/     # ★ 可直接运行的 macOS 应用
+├── HelloElectron-1.0.0-arm64.dmg    # DMG 安装镜像
+├── HelloElectron-1.0.0-arm64-mac.zip  # 压缩包
+├── *.blockmap                 # 增量更新用的 block map
+└── builder-debug.yml          # 构建调试信息
+```
+
+---
+
+## 三、electron-builder 打包全流程解析
+
+### 总体流程
+
+```
+electron-builder
+    │
+    ├── 1. 读取并合并配置（package.json build 字段 + 命令行参数 + electron-builder.yml）
+    │
+    ├── 2. 安装并编译原生依赖（@electron/rebuild）
+    │
+    ├── 3. 下载 Electron 预构建二进制（electron 分发版 Electron.app）
+    │
+    ├── 4. 将应用代码打包为 asar 归档（或保留目录）
+    │
+    ├── 5. 基于 Electron.app 模板，生成最终 .app
+    │      ├── 重命名二进制
+    │      ├── 修改 Info.plist
+    │      ├── 注入应用代码（app.asar 或 app/）
+    │      ├── 替换图标
+    │      └── 重命名 Helper.app
+    │
+    ├── 6. 代码签名（codesign）
+    │
+    ├── 7. 公证（notarization，可选）
+    │
+    └── 8. 打包为 DMG / ZIP 等分发格式
+```
+
+### 步骤1：配置读取与合并
+
+electron-builder 的配置来源优先级（后者覆盖前者）：
+
+1. `package.json` 的 `build` 字段
+2. `electron-builder.yml` 文件
+3. `electron-builder.json5` 文件
+4. 命令行参数（`--config.xxx`）
+
+关键配置项：
+
+```json
+{
+  "build": {
+    "appId": "com.example.hello-electron",     // CFBundleIdentifier
+    "productName": "HelloElectron",             // 应用显示名称，也决定 .app 和可执行文件名
+    "copyright": "Copyright © 2026",            // 版权声明
+    "directories": { "output": "dist" },        // 输出目录
+    "files": [...],                             // 要打包的文件 glob
+    "asar": true,                               // 是否打包为 asar
+    "mac": {
+      "target": ["dmg", "zip"],                 // 输出格式
+      "category": "public.app-category.utilities", // App Store 分类
+      "icon": "build/icon.icns",               // 应用图标
+      "hardenedRuntime": true,                  // 加固运行时
+      "entitlements": "build/entitlements.mac.plist" // 权限声明
+    }
+  }
+}
+```
+
+### 步骤2：原生依赖重编译
+
+如果你的 `node_modules` 包含 C/C++ Native Addon（如 `node-sqlite3`、`sharp`、`node-pty`），这些模块的 `.node` 二进制文件是针对特定 Node.js 版本和架构编译的。
+
+开发时用 `npm install` 安装的 `.node` 文件匹配的是**开发机的 Node.js**，但 Electron 内置的 Node.js 版本可能不同。
+
+**@electron/rebuild 的工作原理**：
+
+```
+@electron/rebuild
+    ├── 读取当前 Electron 的 Node.js ABI 版本号（process.versions.modules）
+    ├── 读取 Electron 的头文件路径（node_modules/electron/dist/Electron.app/Contents/Frameworks/Electron Framework.framework/Headers/）
+    ├── 对每个含 binding.gyp 的原生模块执行：
+    │   node-gyp rebuild
+    │       --target=<electron-version>
+    │       --arch=<arm64/x64>
+    │       --dist-url=https://electronjs.org/headers
+    └── 输出与 Electron 内置 Node.js ABI 兼容的 .node 文件
+```
+
+如果此步骤跳过，运行时会出现经典错误：
+```
+Error: The module was compiled against a different Node.js version using NODE_MODULE_VERSION 93.
+This version of Node.js requires NODE_MODULE_VERSION 131.
+```
+
+### 步骤3：下载 Electron 预构建二进制
+
+electron-builder 不编译 Chromium + Node.js，而是直接使用 **Electron 官方发布的预构建包**。
+
+**下载机制**（由 `@electron/get` 完成）：
+
+```
+@electron/get
+    ├── 确定版本号（读取 node_modules/electron/package.json 中的 version）
+    ├── 确定 CPU 架构（ arm64 / x64 ）
+    ├── 确定平台（ darwin / win32 / linux ）
+    ├── 拼接下载 URL：
+    │   https://github.com/electron/electron/releases/download/v39.8.10/electron-v39.8.10-darwin-arm64.zip
+    ├── 检查缓存目录：
+    │   ~/Library/Caches/electron/
+    │   如果已缓存则直接使用，否则下载
+    └── 解压到：
+        node_modules/electron/dist/
+        └── Electron.app/     ← 这是 Electron 的"空壳"应用
+```
+
+**Electron.app 的内容**（即预构建模板）：
+
+```
+Electron.app/Contents/
+├── Info.plist              ← CFBundleName=Electron, CFBundleIdentifier=com.github.electron
+├── MacOS/
+│   └── Electron            ← 52KB 的启动器（Mach-O 可执行文件）
+├── Frameworks/
+│   ├── Electron Framework.framework/   ← 165MB！Chromium + Node.js + Electron C++ 核心
+│   │   └── Versions/A/
+│   │       ├── Electron Framework      ← 核心动态库
+│   │       ├── Libraries/
+│   │       │   ├── libEGL.dylib        ← EGL OpenGL 绑定
+│   │       │   ├── libGLESv2.dylib     ← OpenGL ES 2.0 实现
+│   │       │   ├── libffmpeg.dylib     ← 音视频编解码（H.264/AAC/VP9...）
+│   │       │   ├── libvk_swiftshader.dylib  ← Vulkan 软件光栅化器
+│   │       │   └── vk_swiftshader_icd.json  ← Vulkan ICD 配置
+│   │       ├── Helpers/
+│   │       │   └── chrome_crashpad_handler  ← 崩溃报告处理进程
+│   │       └── Resources/
+│   │           ├── MainMenu.nib        ← macOS 菜单栏界面定义
+│   │           ├── chrome_100_percent.pak  ← Chromium UI 资源（100% 缩放）
+│   │           ├── chrome_200_percent.pak  ← Chromium UI 资源（200% 缩放）
+│   │           ├── resources.pak       ← Chromium 内置资源
+│   │           ├── icudtl.dat          ← ICU 国际化数据（~10MB）
+│   │           ├── v8_context_snapshot.bin  ← V8 引擎预快照（加速启动）
+│   │           ├── electron.icns       ← Electron 默认图标
+│   │           └── *.lproj/            ← 50+ 语言本地化资源
+│   ├── Electron Helper.app/            ← 主进程 Helper
+│   ├── Electron Helper (GPU).app/      ← GPU 进程
+│   ├── Electron Helper (Plugin).app/   ← 插件进程
+│   ├── Electron Helper (Renderer).app/ ← 渲染进程
+│   ├── Squirrel.framework/             ← 自动更新框架（macOS 专用）
+│   ├── Mantle.framework/               ← Squirrel 的依赖（KVO 包装）
+│   └── ReactiveObjC.framework/         ← Squirrel 的依赖（响应式编程）
+├── Resources/
+│   ├── default_app.asar    ← Electron 默认欢迎页面（当你没有提供应用代码时显示）
+│   └── en.lproj/           ← 本地化
+└── _CodeSignature/
+    └── CodeResources       ← Electron 官方签名
+```
+
+**各组件职责**：
+
+| 组件 | 大小 | 职责 |
+|---|---|---|
+| `MacOS/Electron` | 52KB | 主启动器，加载 Framework 并执行入口 JS |
+| `Electron Framework` | 165MB | Chromium 渲染引擎 + Node.js 运行时 + Electron API 的 C++ 实现 |
+| `libffmpeg.dylib` | 2.3MB | 音视频编解码（H.264、AAC、VP9、Opus 等） |
+| `libEGL.dylib` | 126KB | OpenGL EGL 接口绑定 |
+| `libGLESv2.dylib` | 7MB | OpenGL ES 2.0 实现（软件渲染后备） |
+| `libvk_swiftshader.dylib` | 17MB | Vulkan 软件光栅化器（无 GPU 时的后备） |
+| `icudtl.dat` | ~10MB | ICU 国际化数据（时区、文字排序、日期格式等） |
+| `v8_context_snapshot.bin` | ~1MB | V8 引擎初始堆快照，加速 JS 启动 |
+| `*.pak` 文件 | ~30MB | Chromium 内置 UI 资源 |
+| Helper.app ×4 | 各 ~1MB | 各类型子进程的引导器 |
+| `Squirrel.framework` | ~2MB | macOS 自动更新框架 |
+| `chrome_crashpad_handler` | 1.2MB | 崩溃收集守护进程 |
+
+### 步骤4：应用代码打包（asar）
+
+electron-builder 默认将你的应用代码打包为 **asar 归档**：
+
+```
+你的代码/
+├── main.js
+├── preload.js
+├── index.html
+├── package.json
+└── node_modules/     ← 只包含生产依赖（devDependencies 被 npm 自动排除）
+        ↓
+    asar pack
+        ↓
+app.asar              ← 单文件归档
+```
+
+**asar 格式详解**：
+
+```
+app.asar 文件内部布局：
+┌────────────────────────────────────────────────────────┐
+│  Header (JSON)                                          │
+│  ├── files: {                                          │
+│  │     "/main.js": { "offset": "0", "size": 5576 },  │
+│  │     "/preload.js": { "offset": "5576", "size": 1411 }, │
+│  │     "/index.html": { "offset": "6987", "size": 15322 }, │
+│  │     "/package.json": { "offset": "22309", "size": 114 }, │
+│  │     "/node_modules/..."                             │
+│  │   }                                                 │
+│  └── headerSize: 12345                                 │
+├────────────────────────────────────────────────────────┤
+│  Padding (4-byte alignment)                             │
+├────────────────────────────────────────────────────────┤
+│  File Contents                                          │
+│  ├── main.js content (bytes 0~5575)                    │
+│  ├── preload.js content (bytes 5576~6986)              │
+│  ├── index.html content (bytes 6987~22308)             │
+│  ├── package.json content (bytes 22309~22422)          │
+│  └── node_modules/... contents                         │
+├────────────────────────────────────────────────────────┤
+│  Footer (8 bytes)                                       │
+│  ├── headerSize (4 bytes, little-endian uint32)        │
+│  └── headerSize (4 bytes, little-endian uint32)        │
+│      ← 重复两次，用于从文件末尾反向定位 header          │
+└────────────────────────────────────────────────────────┘
+```
+
+**asar 关键特性**：
+
+1. **随机读取**：不需要解压整个文件，通过 header 中的 offset 可直接 seek 到任意文件内容位置
+2. **Node.js 透明支持**：Electron 修改了 Node.js 的 `fs` 模块，拦截了所有文件操作：
+   ```
+   fs.readFileSync('/app.asar/main.js')
+     → 读取 asar header，找到 main.js 的 offset 和 size
+     → seek 到对应位置，读取原始字节
+     → 返回结果（与读普通文件完全一致）
+   ```
+3. **require() 支持**：`require('./foo')` 从 asar 内部加载模块也正常工作
+4. **不是加密**：`npx asar extract app.asar extracted/` 可以随时解包查看内容
+5. **Integrity 校验**：`Info.plist` 中的 `ElectronAsarIntegrity` 字段记录了 asar 的 SHA256 哈希，运行时校验防止篡改
+
+**何时需要 `asar: false`**：
+
+- 某些 native addon 的 `.node` 文件无法通过 Electron 的 fs 拦截加载（dlopen 不走 Node.js fs）
+- 这时需要设置 `asar: false`，或使用 `asarUnpack` 指定特定文件不打包进 asar
+- `asar: false` 时，应用代码直接以目录形式放入 `Resources/app/`
+
+### 步骤5：基于模板生成最终 .app
+
+这是 electron-builder 的**核心步骤**——将 Electron 官方的空壳 `Electron.app` 定制为你的应用：
+
+```
+Electron.app（模板）                        HelloElectron.app（最终产物）
+─────────────────────                       ────────────────────────────
+Contents/MacOS/Electron                →    Contents/MacOS/HelloElectron
+                                             （重命名可执行文件）
+Contents/Info.plist                    →    Contents/Info.plist
+  CFBundleName: Electron                     CFBundleName: HelloElectron
+  CFBundleIdentifier: com.github.electron    CFBundleIdentifier: com.example.hello-electron
+  CFBundleExecutable: Electron               CFBundleExecutable: HelloElectron
+
+Contents/Resources/electron.icns      →    Contents/Resources/electron.icns
+                                             （替换为你的图标，如有的话）
+
+Contents/Resources/default_app.asar    →    Contents/Resources/app.asar
+  （Electron 默认欢迎页）                     （你的应用代码归档）
+                                       或    Contents/Resources/app/
+                                             （如果 asar: false，则为目录）
+
+Frameworks/Electron Helper.app        →    Frameworks/HelloElectron Helper.app
+Frameworks/Electron Helper (GPU).app  →    Frameworks/HelloElectron Helper (GPU).app
+Frameworks/Electron Helper (Plugin).app→   Frameworks/HelloElectron Helper (Plugin).app
+Frameworks/Electron Helper (Renderer).app→ Frameworks/HelloElectron Helper (Renderer).app
+                                             （所有 Helper.app 重命名）
+
+Frameworks/下的其他内容（Electron Framework.framework、
+Squirrel.framework 等）保持不变
+```
+
+**具体操作细节**：
+
+1. **复制整个 Electron.app** 作为基础
+2. **重命名主可执行文件**：`MacOS/Electron` → `MacOS/${productName}`
+3. **修改主 Info.plist**：替换所有 `Electron` 为你的 `productName`，设置 `appId`、`version`、`copyright` 等
+4. **注入应用代码**：
+   - `asar: true`（默认）→ 将代码打包为 `app.asar` 放入 `Resources/`
+   - `asar: false` → 将代码目录复制到 `Resources/app/`
+5. **重命名所有 Helper.app**：`Electron Helper.app` → `${productName} Helper.app`，同时修改其内部 Info.plist 的 `CFBundleDisplayName`、`CFBundleExecutable`、`CFBundleIdentifier`
+6. **替换图标**：如果配置了自定义 `.icns`，替换 `Resources/electron.icns`
+7. **删除默认页面**：移除 `Resources/default_app.asar`（你的 app.asar 会替代它）
+
+### 步骤6：代码签名
+
+macOS 的代码签名由 `codesign` 命令完成，electron-builder 封装了这一过程：
+
+```
+签名顺序（从内到外）：
+1. Helper.app 内的可执行文件
+2. Helper.app 本身
+3. Electron Framework.framework 内的所有动态库
+4. Electron Framework.framework 本身
+5. 其他 .framework
+6. 主可执行文件
+7. 最终对整个 .app 签名
+```
+
+**签名依赖**：
+
+| 依赖项 | 说明 |
+|---|---|
+| Apple Developer 证书 | 从 Apple Developer 获取，安装到 Keychain |
+| `codesign` 命令 | Xcode Command Line Tools 自带 |
+| Entitlements 文件 | 声明应用需要的权限（网络、文件、摄像头等） |
+
+**无证书情况**：
+
+electron-builder 检测到没有有效开发者证书时，会回退到 **ad-hoc 签名**（`codesign --sign -`），这样应用可以在本机运行，但无法分发给其他用户（被 Gatekeeper 拦截）。
+
+### 步骤7：DMG / ZIP 打包
+
+签名后的 .app 可进一步打包为分发格式：
+
+**DMG（Disk Image）**：
+```
+HelloElectron-1.0.0-arm64.dmg
+├── HelloElectron.app          ← 拖入 Applications 的安装方式
+├── Applications (快捷方式)    ← 指向 /Applications
+└── 背景图片                   ← DMG 窗口自定义背景
+```
+
+用户双击 DMG → 挂载为虚拟磁盘 → 将 .app 拖入 Applications 文件夹 → 完成"安装"。
+
+**ZIP**：
+直接将 .app 压缩为 `.zip`，用户解压后拖入 Applications。适用于不需要 DMG 美化或体积更小的场景。
+
+---
+
+## 四、应用启动运行原理
+
+### 从双击到页面渲染
+
+```
+用户双击 HelloElectron.app
+    │
+    ├── 1. Launch Services 读取 Info.plist
+    │      找到 CFBundleExecutable = HelloElectron
+    │
+    ├── 2. 加载 MacOS/HelloElectron（52KB 启动器）
+    │      该启动器通过 dlopen 加载 Electron Framework.framework
+    │
+    ├── 3. Electron Framework 初始化
+    │      ├── 初始化 V8 引擎
+    │      ├── 初始化 Node.js 运行时
+    │      ├── 初始化 Chromium 主进程（browser process）
+    │      ├── 读取 app.asar 中的 package.json → 找到 main: "main.js"
+    │      └── 以 Node.js 执行 app.asar/main.js
+    │
+    ├── 4. main.js 执行
+    │      ├── app.whenReady() 等待 Chromium 初始化完成
+    │      ├── new BrowserWindow() 创建窗口
+    │      │     ├── fork出 Helper (Renderer).app 进程
+    │      │     ├── fork出 Helper (GPU).app 进程
+    │      │     └── 设置 XPC 通信通道
+    │      └── win.loadFile('index.html') 加载页面
+    │
+    └── 5. 渲染进程启动
+           ├── Helper (Renderer).app 加载 Chromium 渲染引擎
+           ├── 解析 HTML → 构建 DOM 树
+           ├── 解析 CSS → 构建渲染树
+           ├── 执行 JavaScript（含 preload 注入的 window.api）
+           └── GPU 进程将渲染结果绘制到窗口
+```
+
+### 多进程架构在 macOS 上的体现
+
+```
+活动监视器中看到：
+
+HelloElectron               ← 主进程（Node.js + Chromium Browser Process）
+HelloElectron Helper (GPU)  ← GPU 进程（OpenGL/Metal 渲染）
+HelloElectron Helper (Renderer) ← 渲染进程（每个 BrowserWindow 一个）
+HelloElectron Helper (Plugin)   ← 插件进程（Flash 等，罕见）
+chrome_crashpad_handler    ← 崩溃报告守护进程
+```
+
+每个 Helper.app 都是**独立的进程**，通过 Mach IPC 通信。这种多进程架构是 Chromium 的安全核心——渲染进程被沙箱隔离，即使被攻击也无法访问主进程的系统权限。
+
+---
+
+## 五、electron-builder 核心依赖分析
+
+### 直接依赖树
+
+```
+electron-builder
+├── app-builder-bin           ← Rust 编写的高速文件操作工具
+│   （负责 asar 打包、文件复制、DMG 生成等重 IO 操作）
+│
+├── builder-util              ← 通用工具库（日志、HTTP、临时目录）
+│   └── @electron/rebuild     ← 原生模块重编译
+│
+├── dmg-builder               ← DMG 镜像生成
+│
+├── electron-builder-lib      ← 打包核心逻辑
+│   ├── electron-publish      ← 发布到 GitHub Releases / S3 等
+│   ├── @electron/get         ← 下载 Electron 预构建二进制
+│   │   └── @electron/asar    ← asar 归档打包/解包
+│   ├── electron-macos-sign   ← macOS 代码签名和公证
+│   ├── app-builder-lib       ← 平台特定打包逻辑
+│   └── semver                ← 版本号处理
+│
+└── electron-builder-squirrel-windows  ← Windows 自动更新
+```
+
+### 关键依赖详解
+
+#### 1. app-builder-bin（Rust 加速层）
+
+electron-builder 的性能瓶颈在文件 IO——复制成千上万的小文件（node_modules）、打包 asar、生成 DMG。这些操作用 Node.js 实现很慢，因此 electron-builder 用 **Rust** 重写了关键路径：
+
+```
+app-builder-bin（Rust 编译的单二进制）
+├── asar 打包/解包          ← 替代 @electron/asar 的纯 JS 实现
+├── 文件过滤和复制          ← 大量 glob 匹配 + 并行 IO
+├── DMG 生成               ← 调用 macOS 的 hdiutil
+└── 代码签名封装            ← 调用 codesign 命令
+```
+
+npm 安装时，`app-builder-bin` 会下载对应平台的预编译二进制（类似 electron 本身的分发方式）。
+
+#### 2. @electron/get（Electron 二进制下载器）
+
+```
+@electron/get
+├── 确定版本和平台
+├── 拼接 GitHub Release URL
+├── 检查缓存：
+│   macOS: ~/Library/Caches/electron/
+│   Windows: %LOCALAPPDATA%\electron\Cache\
+│   Linux: ~/.cache/electron/
+├── 下载（支持断点续传、镜像源）
+│   环境变量 ELECTRON_MIRROR 可切换镜像
+│   如中国用户设置：ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
+└── 校验 SHA256（从 SHASUMS256.txt 读取）
+```
+
+#### 3. @electron/rebuild（原生模块重编译）
+
+```
+@electron/rebuild
+├── 扫描 node_modules 中的 binding.gyp
+├── 确定目标 Electron 的 Node.js ABI 版本
+├── 下载 Electron 版对应的 Node.js 头文件
+├── 为每个原生模块执行：
+│   node-gyp rebuild
+│     --target=<electron-version>
+│     --runtime=electron
+│     --dist-url=https://electronjs.org/headers
+│     --arch=<arm64/x64>
+└── 输出兼容的 .node 文件
+```
+
+#### 4. @electron/asar（归档格式实现）
+
+```
+@electron/asar
+├── asar.createPackage(directory, output)
+│   ├── 遍历目录，记录每个文件的相对路径、大小、偏移量
+│   ├── 构建 JSON header
+│   ├── 计算 headerSize 和 padding
+│   └── 写入：header + padding + file contents + footer
+│
+├── asar.extractPackage(archive, dest)
+│   ├── 读取 footer（最后 8 字节）获取 headerSize
+│   ├── 解析 header JSON
+│   └── 根据 offset 和 size 逐个提取文件
+│
+└── asar.listPackage(archive)
+    └── 返回文件列表
+```
+
+---
+
+## 六、MacOS Electron.app → 你的应用：变换对照表
+
+| 属性 | Electron.app（模板） | HelloElectron.app（产物） | 修改方式 |
+|---|---|---|---|
+| 目录名 | `Electron.app` | `HelloElectron.app` | 重命名 |
+| 主可执行文件名 | `MacOS/Electron` | `MacOS/HelloElectron` | 重命名 |
+| CFBundleName | `Electron` | `HelloElectron` | 修改 Info.plist |
+| CFBundleDisplayName | `Electron` | `HelloElectron` | 修改 Info.plist |
+| CFBundleIdentifier | `com.github.electron` | `com.example.hello-electron` | 修改 Info.plist |
+| CFBundleExecutable | `Electron` | `HelloElectron` | 修改 Info.plist |
+| CFBundleIconFile | `electron.icns` | `electron.icns` 或自定义 | 替换文件 |
+| Helper.app 名 | `Electron Helper.app` | `HelloElectron Helper.app` | 重命名 |
+| Helper CFBundleIdentifier | `com.github.electron.helper` | `com.example.hello-electron.helper` | 修改 Info.plist |
+| 应用代码 | `Resources/default_app.asar` | `Resources/app.asar` | 替换文件 |
+| 入口 JS | Electron 默认欢迎页 | 你的 main.js | 随 app.asar 注入 |
+
+---
+
+## 七、包体大小分析
+
+以 HelloElectron 为例（arm64, macOS）：
+
+```
+HelloElectron.app/ = 255MB 总计
+│
+├── Electron Framework.framework/ = 253MB (99.2%)
+│   ├── Electron Framework (单一动态库) = 165MB     ← Chromium + Node.js + Electron C++
+│   ├── Resources/ (本地化+Chromium资源) ≈ 50MB
+│   ├── Libraries/ = 26MB
+│   │   ├── libvk_swiftshader.dylib = 17MB           ← Vulkan 软件光栅化
+│   │   ├── libGLESv2.dylib = 7MB                     ← OpenGL ES
+│   │   ├── libffmpeg.dylib = 2.3MB                   ← 音视频编解码
+│   │   └── libEGL.dylib = 126KB                      ← EGL 接口
+│   └── Helpers/
+│       └── chrome_crashpad_handler = 1.2MB
+│
+├── Frameworks/ (除 Electron Framework 外) ≈ 5MB
+│   ├── Squirrel.framework = 2MB                      ← 自动更新
+│   ├── ReactiveObjC.framework = 1.5MB                ← Squirrel 依赖
+│   ├── Mantle.framework = 0.5MB                      ← Squirrel 依赖
+│   ├── HelloElectron Helper.app ≈ 0.5MB
+│   ├── HelloElectron Helper (GPU).app ≈ 0.5MB
+│   ├── HelloElectron Helper (Renderer).app ≈ 0.5MB
+│   └── HelloElectron Helper (Plugin).app ≈ 0.5MB
+│
+├── MacOS/HelloElectron = 52KB                         ← 启动器
+│
+└── Resources/ ≈ 0.3MB
+    ├── app/ (或 app.asar)                             ← 你的应用代码
+    ├── electron.icns
+    └── *.lproj/ (本地化)
+```
+
+**结论**：255MB 中，你的应用代码通常只占几百 KB 到几 MB，**99% 的体积是 Electron 运行时**（Chromium 渲染引擎 + Node.js + 媒体编解码器）。
+
+---
+
+## 八、electron-builder 执行时序图
+
+```
+npm run build
+    │
+    ▼
+electron-builder ──────────────────────────────────────────────────────
+    │
+    ├── 读取配置
+    │   └── 合并 package.json.build + electron-builder.yml + CLI 参数
+    │
+    ├── 检查 devDependencies.electron 版本
+    │   └── 确定 Electron 版本号 (如 39.8.10)
+    │
+    ├── @electron/rebuild
+    │   └── 重编译 native addons（如有）
+    │
+    ├── @electron/get
+    │   ├── 检查缓存 ~/Library/Caches/electron/
+    │   ├── 缓存命中 → 直接使用
+    │   └── 缓存未命中 → 下载 electron-v39.8.10-darwin-arm64.zip
+    │                    → 校验 SHA256
+    │                    → 解压到 node_modules/electron/dist/Electron.app
+    │
+    ├── 过滤应用文件
+    │   ├── 读取 build.files glob 列表
+    │   ├── 排除 devDependencies 中包的文件
+    │   └── 生成最终文件清单
+    │
+    ├── asar 打包（如 asar: true）
+    │   ├── app-builder-bin asar pack
+    │   └── 生成 app.asar + 计算完整性哈希
+    │
+    ├── 工作目录准备
+    │   ├── 复制 Electron.app → 临时目录
+    │   ├── 重命名 MacOS/Electron → MacOS/${productName}
+    │   ├── 重命名所有 Helper.app
+    │   ├── 删除 Resources/default_app.asar
+    │   ├── 放入 app.asar（或 app/ 目录）
+    │   ├── 替换图标 .icns（如有）
+    │   └── 修改所有 Info.plist
+    │
+    ├── 代码签名
+    │   ├── 签名 Helper 可执行文件
+    │   ├── 签名 Framework 内动态库
+    │   ├── 签名 Framework 本身
+    │   ├── 签名主可执行文件
+    │   └── 签名整个 .app
+    │
+    ├── 公证（如配置了）
+    │   ├── xcrun notarytool submit
+    │   └── 等待 Apple 服务器返回结果
+    │
+    └── 分发格式打包
+        ├── DMG 创建
+        │   ├── 创建临时 HFS+ 分区
+        │   ├── 复制 .app + Applications 快捷方式
+        │   ├── 设置窗口背景和图标位置
+        │   └── hdiutil convert 为压缩 DMG
+        ├── ZIP 创建
+        └── 生成 blockmap（增量更新用）
+```
+
+---
+
+## 九、关键问题 FAQ
+
+### Q1：为什么 .app 这么大？能缩小吗？
+
+运行时占 99%，其中 `Electron Framework`（165MB）就是 Chromium + Node.js 的合并编译产物。可以做的优化：
+
+- 使用 `electron-webpack` 做 tree-shaking 减少 `node_modules` 体积
+- 配置 `build.files` 精确包含所需文件
+- 删除不需要的语言包（`*.lproj`）
+- 如果不用自动更新，可排除 `Squirrel.framework`（节省 ~4MB）
+- 如果不需要视频播放，可排除 `libffmpeg.dylib`（节省 ~2MB，但 HTML5 `<video>` 将失效）
+
+### Q2：asar 安全吗？能防止代码被查看吗？
+
+**不能**。asar 只是归档格式，不是加密。任何人都可以用 `npx asar extract app.asar ./extracted` 解包查看你的源代码。如果需要保护代码，应使用 JavaScript 混淆器（如 `javascript-obfuscator`）在 asar 打包前处理。
+
+### Q3：52KB 的主可执行文件做了什么？
+
+它是一个极薄的启动器，只做了三件事：
+1. 通过 `dlopen` 加载 `Electron Framework.framework`
+2. 传递命令行参数
+3. 调用 Framework 的入口函数
+
+实际逻辑全部在 165MB 的 `Electron Framework` 动态库中。
+
+### Q4：为什么需要那么多 Helper.app？
+
+Chromium 的安全模型要求不同类型的操作运行在不同进程中：
+
+| Helper 进程 | 职责 | 沙箱 |
+|---|---|---|
+| Helper (Renderer) | 运行网页 JS、DOM 解析、页面渲染 | 是 |
+| Helper (GPU) | OpenGL/Metal 硬件加速渲染 | 是 |
+| Helper (Plugin) | 运行浏览器插件（如 PDF 查看器） | 是 |
+| Helper (默认) | 主进程的辅助进程 | 否 |
+
+每个 Helper.app 都是一个完整的 macOS Application Bundle，因为 macOS 要求每个进程有自己的 Info.plist 来声明权限和身份。
+
+### Q5：不签名能运行吗？
+
+可以，但有限制：
+- 本机开发：可以正常运行
+- 分发给他人：默认被 macOS Gatekeeper 拦截（"应用已损坏"提示）
+- 绕过方式：用户手动执行 `xattr -cr MyApp.app`，但不推荐
+
+### Q6：如果不使用 electron-builder，能手动打包吗？
+
+完全可以。手动步骤：
+```bash
+# 1. 下载 Electron.app
+npx @electron/get
+
+# 2. 复制并重命名
+cp -R node_modules/electron/dist/Electron.app ./HelloElectron.app
+mv HelloElectron.app/Contents/MacOS/Electron HelloElectron.app/Contents/MacOS/HelloElectron
+
+# 3. 修改 Info.plist（用 PlistBuddy 或 defaults write）
+
+# 4. 放入应用代码
+npx asar pack ./src HelloElectron.app/Contents/Resources/app.asar
+
+# 5. 签名
+codesign --deep --force --sign - HelloElectron.app
+```
+
+electron-builder 本质上就是将以上步骤自动化，并处理了大量边界情况和平台差异。