构建、打包与分发

本章目标

  • 理解 Electron 应用的打包产物结构,知道 app.asar 里到底装了什么。
  • 会在 Electron Forge 与 electron-builder 之间做选型,并完成可发布构建。
  • 掌握包体积优化的完整清单:依赖裁剪、资源压缩、按平台拆分。
  • 理解代码签名、公证、增量更新的原理与流程。

打包到底做了什么

Electron 应用发布时不是「一个 exe」,而是一个包含 Chromium、Node.js、你的代码与资源的完整运行时。

1MyApp.app / MyApp/
2├── Electron Framework / electron.dll   # Chromium + Node 运行时
3├── Resources/
4│   ├── app.asar                        # 你的代码与资源
5│   └── app.asar.unpacked/              # 需要真实文件路径的内容
6├── Info.plist / MyApp.exe.manifest
7└── locales/                            # Chromium 语言包

打包工具做四件事:

  1. 复制 Electron 运行时到产物目录。
  2. 把你的应用代码与生产依赖打进 app.asar。
  3. 生成安装器(dmg/exe/msi/deb 等)。
  4. 可选:签名、公证、生成更新元数据。

Forge 与 electron-builder 选型

维度Electron Forgeelectron-builder
维护方Electron 官方社区(生态成熟)
开发集成内置 Webpack/Vite 模板、start/package/make主要专注打包,开发需自行配置
配置方式forge.config.ts + makerspackage.json#build 或 electron-builder.yml
安装器Squirrel.Windows、DMG、ZIP、DEB、RPMNSIS、NSIS Web、Portable、DMG、ZIP、AppImage、Snap
自动更新配合 update-electron-app / Squirrel内置 electron-updater,provider 丰富
差量更新依赖 Squirrel 机制blockmap 增量下载
适合官方推荐、从零起步、模板化项目复杂分发、多平台、灰度与私有源

经验建议:

  • 新项目、团队希望「少配置」:Forge + Vite 模板。
  • 需要 NSIS 安装器、差分更新、私有更新源、多平台矩阵:electron-builder。
  • 两者都能做出合格产物,关键是把签名、更新、体积治理纳入流水线。

Electron Forge 配置

1// forge.config.ts
2import type { ForgeConfig } from '@electron-forge/shared-types';
3import { MakerSquirrel } from '@electron-forge/maker-squirrel';
4import { MakerZIP } from '@electron-forge/maker-zip';
5import { MakerDMG } from '@electron-forge/maker-dmg';
6import { MakerDeb } from '@electron-forge/maker-deb';
7import { VitePlugin } from '@electron-forge/plugin-vite';
8
9const config: ForgeConfig = {
10  packagerConfig: {
11    asar: true,
12    name: 'MyApp',
13    appBundleId: 'com.example.myapp',
14    icon: './resources/icon',
15    ignore: [
16      /^\/src/,
17      /^\/\.git/,
18      /^\/release/,
19      /^\/docs/,
20    ],
21  },
22  rebuildConfig: {},
23  makers: [
24    new MakerSquirrel({ name: 'my_app' }, ['win32']),
25    new MakerDMG({ format: 'ULFO' }, ['darwin']),
26    new MakerZIP({}, ['darwin', 'linux']),
27    new MakerDeb({}, ['linux']),
28  ],
29  plugins: [
30    new VitePlugin({
31      build: [
32        { entry: 'src/main.ts', config: 'vite.main.config.ts' },
33        { entry: 'src/preload.ts', config: 'vite.preload.config.ts' },
34      ],
35      renderer: [{ name: 'main_window', config: 'vite.renderer.config.ts' }],
36    }),
37  ],
38};
39
40export default config;

常用命令:

1npm start          # 开发
2npm run package    # 生成未压缩的应用目录,便于调试
3npm run make       # 生成安装器

产物在 out/:out/MyApp-darwin-arm64/MyApp.app、out/make/...。

electron-builder 配置

1# electron-builder.yml
2appId: com.example.myapp
3productName: MyApp
4copyright: Copyright © 2026 Example
5
6directories:
7  output: release
8  buildResources: build
9
10files:
11  - dist/**/*
12  - package.json
13  - "!**/*.map"
14  - "!**/node_modules/**/{test,__tests__,docs,example,examples}/**"
15
16asar: true
17asarUnpack:
18  - "**/*.node"
19  - resources/native/**
20
21compression: maximum
22removePackageScripts: true
23npmRebuild: true
24
25mac:
26  category: public.app-category.productivity
27  target:
28    - target: dmg
29      arch: [x64, arm64]
30  hardenedRuntime: true
31  gatekeeperAssess: false
32  entitlements: build/entitlements.mac.plist
33  entitlementsInherit: build/entitlements.mac.plist
34
35win:
36  target:
37    - target: nsis
38      arch: [x64, arm64]
39  icon: build/icon.ico
40
41nsis:
42  oneClick: false
43  perMachine: false
44  allowToChangeInstallationDirectory: true
45  deleteAppDataOnUninstall: false
46
47publish:
48  provider: github
49  releaseType: release
1npx electron-builder --mac --win --x64 --arm64

asar:是什么,什么时候要解包

asar 是把目录打包成单个归档文件的格式,减少文件数量、加快读取、避免路径过长。

1# 查看 asar 内容
2npx asar list release/mac/MyApp.app/Contents/Resources/app.asar
3
4# 解包检查
5npx asar extract release/mac/MyApp.app/Contents/Resources/app.asar /tmp/app-asar

必须 asarUnpack 的内容:

内容原因
.node 原生模块需要真实文件路径才能 dlopen
需要被外部程序执行的二进制系统 API 不接受 asar 虚拟路径
部分需要 fs.realpath 的资源asar 内路径不是真实路径
某些子进程脚本child_process 需要真实路径

不需要解包的内容:JS、CSS、图片、字体、JSON。解包越多,安装包越大、文件数越多,启动与更新成本越高。

包体积优化清单

1. 依赖裁剪

1# 检查生产依赖
2npm ls --omit=dev --depth=0
  • 前端依赖能打进 bundle 的,不要留在 node_modules。
  • 只在构建时使用的包必须放 devDependencies。
  • electron-builder 的 files 白名单只保留运行必需内容。
  • 删除 .map、测试、示例、文档、TypeScript 源码。

2. 资源压缩

  • 图片转 WebP/AVIF,按显示尺寸导出,避免 2x/3x 原图直接打包。
  • 字体做子集化,只保留用到的字符。
  • 删除未使用的语言包:electron-builder 可用 electronLanguages 限制。
  • 音视频资源按需下载,不要全部塞进安装包。

3. 运行时裁剪

  • 关闭不需要的 Chromium 特性(谨慎,需回归测试)。
  • 精简 locales。
  • 不需要的 node_modules 依赖通过 files 排除。

4. 体积分析

1# macOS/Linux 查看应用目录体积
2du -sh release/mac/MyApp.app
3du -sh release/mac/MyApp.app/Contents/Resources/app.asar
4du -sh release/mac/MyApp.app/Contents/Frameworks/Electron\ Framework.framework
5
6# Windows 查看安装包
7ls -lh release/*.exe

建议在 CI 中记录每次构建的:

指标目的
安装包体积防止依赖膨胀
app.asar 体积定位业务代码增长
app.asar.unpacked 体积原生模块与资源增长
文件数量影响安装与更新速度

多平台构建

macOS 架构

架构说明
x64Intel Mac
arm64Apple Silicon
universal同时包含两种架构,体积约翻倍
1mac:
2  target:
3    - target: dmg
4      arch: [universal]

universal 构建要求所有原生依赖都提供双架构版本,否则会失败。多数团队选择分别发布 x64 与 arm64,安装包更小。

Windows 架构

1win:
2  target:
3    - target: nsis
4      arch: [x64, arm64]

ARM64 Windows 设备建议单独验证,尤其是原生模块与安装器行为。

CI 矩阵

1# .github/workflows/build.yml
2name: build
3
4on:
5  push:
6    tags: ['v*']
7
8jobs:
9  build:
10    strategy:
11      matrix:
12        os: [macos-14, windows-2022]
13    runs-on: ${{ matrix.os }}
14    steps:
15      - uses: actions/checkout@v4
16      - uses: actions/setup-node@v4
17        with:
18          node-version: 22
19          cache: npm
20      - run: npm ci
21      - run: npm run build
22      - run: npx electron-builder --publish never
23      - uses: actions/upload-artifact@v4
24        with:
25          name: dist-${{ matrix.os }}
26          path: release/*

签名密钥放在 CI Secret 中,不要写进仓库。

代码签名与公证

Windows

  • 使用 Authenticode 证书对 .exe 与安装器签名。
  • 证书可以是 PFX 文件,也可以放在硬件令牌/云签名服务中。
  • 未签名的应用会触发 SmartScreen 警告,下载转化率明显下降。
1win:
2  certificateFile: build/cert.pfx
3  certificatePassword: ${env.WIN_CERT_PASSWORD}
4  signingHashAlgorithms: [sha256]
5  rfc3161TimeStampServer: http://timestamp.digicert.com

macOS

macOS 要求两层:

  1. 代码签名:使用 Developer ID 证书签名。
  2. 公证(Notarization):把产物提交给 Apple 扫描,通过后分发。
1mac:
2  hardenedRuntime: true
3  gatekeeperAssess: false
4  entitlements: build/entitlements.mac.plist
5  entitlementsInherit: build/entitlements.mac.plist
6  notarize: true

CI 中提供:

1export APPLE_ID="dev@example.com"
2export APPLE_APP_SPECIFIC_PASSWORD="xxxx-xxxx-xxxx-xxxx"
3export APPLE_TEAM_ID="ABCDE12345"

entitlements.mac.plist 示例:

1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
3  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
4<plist version="1.0">
5  <dict>
6    <key>com.apple.security.cs.allow-jit</key>
7    <true/>
8    <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
9    <true/>
10    <key>com.apple.security.cs.disable-library-validation</key>
11    <true/>
12    <key>com.apple.security.network.client</key>
13    <true/>
14  </dict>
15</plist>

disable-library-validation 会放宽动态库加载限制,只在确实需要加载未签名原生模块时使用。

增量更新与 Squirrel

Squirrel 机制

Squirrel.Windows / Squirrel.Mac 的基本流程:

  1. 应用启动后检查更新源。
  2. 下载新版本包到本地缓存。
  3. 校验签名与版本。
  4. 退出时由 Squirrel 替换应用目录。
  5. 下次启动运行新版本。

Electron 内置的 autoUpdater 就是基于 Squirrel 的封装,Windows 与 macOS 支持较好,Linux 不支持。

blockmap 增量下载

electron-builder + electron-updater 会为每个安装包生成 .blockmap 文件,记录文件分块哈希。更新时只下载变化的块,再在本地重组。

1release/
2├── MyApp-1.2.0.exe
3├── MyApp-1.2.0.exe.blockmap
4├── latest.yml
5└── MyApp-1.2.0.dmg

增量效果取决于变化内容:JS bundle 变化通常只影响少量块;替换整个资源包则可能接近全量。

发布渠道

1publish:
2  provider: generic
3  url: https://updates.example.com/myapp/${channel}
4  channel: stable

常见策略:

  • stable / beta / internal 三个渠道。
  • 服务端按用户分桶返回不同 latest.yml。
  • 保留最近 2–3 个版本,支持回滚。

常见打包问题

现象原因处理
打包后白屏loadFile 路径基于源码目录用 app.getAppPath() 或 __dirname 计算
Cannot find module依赖被 files 排除或放在 devDependencies检查白名单与依赖分类
原生模块加载失败ABI 不匹配或未解包electron-rebuild + asarUnpack
macOS 无法打开未签名/未公证签名 + notarytool
Windows SmartScreen 警告未签名或证书信誉不足使用 EV/云签名,积累信誉
安装后更新失败更新源地址/签名/版本号错误检查 latest.yml 与 channel
包体积突然变大新增依赖或资源未压缩CI 体积门禁 + 差异分析

本章小结

  • 打包产物 = Electron 运行时 + app.asar + 安装器,体积主要来自 Chromium 与业务依赖。
  • Forge 适合官方一体化流程,electron-builder 适合复杂分发与差分更新。
  • 体积优化从依赖裁剪、资源压缩、files 白名单、asarUnpack 边界四方面入手。
  • 签名与公证是分发的硬门槛,必须纳入 CI。
  • 增量更新依赖 Squirrel 或 blockmap,发布流程要支持灰度与回滚。

参考资料