app.asar 里到底装了什么。Electron 应用发布时不是「一个 exe」,而是一个包含 Chromium、Node.js、你的代码与资源的完整运行时。
打包工具做四件事:
app.asar。| 维度 | Electron Forge | electron-builder |
|---|---|---|
| 维护方 | Electron 官方 | 社区(生态成熟) |
| 开发集成 | 内置 Webpack/Vite 模板、start/package/make | 主要专注打包,开发需自行配置 |
| 配置方式 | forge.config.ts + makers | package.json#build 或 electron-builder.yml |
| 安装器 | Squirrel.Windows、DMG、ZIP、DEB、RPM | NSIS、NSIS Web、Portable、DMG、ZIP、AppImage、Snap |
| 自动更新 | 配合 update-electron-app / Squirrel | 内置 electron-updater,provider 丰富 |
| 差量更新 | 依赖 Squirrel 机制 | blockmap 增量下载 |
| 适合 | 官方推荐、从零起步、模板化项目 | 复杂分发、多平台、灰度与私有源 |
经验建议:
常用命令:
产物在 out/:out/MyApp-darwin-arm64/MyApp.app、out/make/...。
asar 是把目录打包成单个归档文件的格式,减少文件数量、加快读取、避免路径过长。
必须 asarUnpack 的内容:
| 内容 | 原因 |
|---|---|
.node 原生模块 | 需要真实文件路径才能 dlopen |
| 需要被外部程序执行的二进制 | 系统 API 不接受 asar 虚拟路径 |
部分需要 fs.realpath 的资源 | asar 内路径不是真实路径 |
| 某些子进程脚本 | child_process 需要真实路径 |
不需要解包的内容:JS、CSS、图片、字体、JSON。解包越多,安装包越大、文件数越多,启动与更新成本越高。
node_modules。devDependencies。files 白名单只保留运行必需内容。.map、测试、示例、文档、TypeScript 源码。electronLanguages 限制。locales。node_modules 依赖通过 files 排除。建议在 CI 中记录每次构建的:
| 指标 | 目的 |
|---|---|
| 安装包体积 | 防止依赖膨胀 |
app.asar 体积 | 定位业务代码增长 |
app.asar.unpacked 体积 | 原生模块与资源增长 |
| 文件数量 | 影响安装与更新速度 |
| 架构 | 说明 |
|---|---|
x64 | Intel Mac |
arm64 | Apple Silicon |
universal | 同时包含两种架构,体积约翻倍 |
universal 构建要求所有原生依赖都提供双架构版本,否则会失败。多数团队选择分别发布 x64 与 arm64,安装包更小。
ARM64 Windows 设备建议单独验证,尤其是原生模块与安装器行为。
签名密钥放在 CI Secret 中,不要写进仓库。
.exe 与安装器签名。macOS 要求两层:
CI 中提供:
entitlements.mac.plist 示例:
disable-library-validation 会放宽动态库加载限制,只在确实需要加载未签名原生模块时使用。
Squirrel.Windows / Squirrel.Mac 的基本流程:
Electron 内置的 autoUpdater 就是基于 Squirrel 的封装,Windows 与 macOS 支持较好,Linux 不支持。
electron-builder + electron-updater 会为每个安装包生成 .blockmap 文件,记录文件分块哈希。更新时只下载变化的块,再在本地重组。
增量效果取决于变化内容:JS bundle 变化通常只影响少量块;替换整个资源包则可能接近全量。
常见策略:
stable / beta / internal 三个渠道。latest.yml。| 现象 | 原因 | 处理 |
|---|---|---|
| 打包后白屏 | loadFile 路径基于源码目录 | 用 app.getAppPath() 或 __dirname 计算 |
Cannot find module | 依赖被 files 排除或放在 devDependencies | 检查白名单与依赖分类 |
| 原生模块加载失败 | ABI 不匹配或未解包 | electron-rebuild + asarUnpack |
| macOS 无法打开 | 未签名/未公证 | 签名 + notarytool |
| Windows SmartScreen 警告 | 未签名或证书信誉不足 | 使用 EV/云签名,积累信誉 |
| 安装后更新失败 | 更新源地址/签名/版本号错误 | 检查 latest.yml 与 channel |
| 包体积突然变大 | 新增依赖或资源未压缩 | CI 体积门禁 + 差异分析 |
app.asar + 安装器,体积主要来自 Chromium 与业务依赖。files 白名单、asarUnpack 边界四方面入手。