electron-builder

一句话：社区主流的 Electron 打包分发全家桶——“auto update support out of the box”。14.6k stars，electron-userland 出品。

定位

只管打包期（不管开发服务器，开发构建交给 electron-vite 或 webpack）：把构建产物变成各平台安装包，附赠签名、公证、自动更新、发布。

核心能力

能力	说明
多格式安装包	macOS：dmg/zip/mas；Windows：nsis/msi/squirrel/appx；Linux：deb/rpm/AppImage/snap
签名 + 公证	macOS osxSign/notarize、Windows 证书；凭据走环境变量，CI 友好
自动更新	内置 `electron-updater`（配 `autoUpdater`），支持 GitHub/S3/通用静态服务器等更新源，含差量更新
发布	一键发布 GitHub Releases / S3 / Bintray（`publish` 配置）
依赖处理	自动区分 dev/prod 依赖；`install-app-deps` 重建原生模块

最小实例

npm install electron-builder --save-dev

配置可写 package.json 的 build 字段，推荐独立 electron-builder.yml：

# electron-builder.yml
appId: com.example.app
productName: MyApp
files:
  - out/**/*          # electron-vite 的产物目录
  - package.json
mac:
  target: [dmg, zip]
  category: public.app-category.developer-tools
win:
  target: [nsis]
linux:
  target: [AppImage]

独立配置文件的格式与自动发现优先级（app-builder-lib 源码确认，按顺序找第一个存在即可，不会合并多个）：

electron-builder.yml / .yaml / .json / .json5 / .toml / .js / .cjs / .ts

因此：

electron-builder.yml 与 electron-builder.ts 都能被自动发现；同时存在时 yml 先被发现、ts 不生效
文件名前缀固定是 electron-builder。所谓 electron-builder.config.ts 不是默认文件名，需显式指定：electron-builder --config electron-builder.config.ts
TS 配置里能导出函数并根据 meta 动态计算：

// electron-builder.ts（能被自动发现）
import type { Configuration } from 'electron-builder'
 
export default {
  appId: 'com.example.app',
  productName: 'MyApp',
  files: ['out/**/*', 'package.json']
} satisfies Configuration

适用一条经验：配置是静态声明值就选 YAML（团队可读、字段最省）；要按环境函数计算、需要 TS 类型提示或复用构建脚本变量时再选 TS/JS。TS 注意 electron-builder 26 用 jiti 加载，无需预编译。

package.json：

{
  "scripts": {
    "dist": "electron-builder",
    "dist:mac": "electron-builder --mac",
    "dist:win": "electron-builder --win",
    "dist:linux": "electron-builder --linux"
  }
}

npm run dist                          # 打包当前平台
npx electron-builder --publish always # 打包并发布
npx electron-builder install-app-deps # 有原生依赖时先重建（见 npm rebuild 笔记）

自动更新（与 Forge 的差异点）

应用侧装 electron-updater，主进程：

const { autoUpdater } = require('electron-updater')
autoUpdater.checkForUpdatesAndNotify()   // 默认读 GitHub Releases

更新源可选：github（默认）、generic（任意静态文件服务器）、s3 等——比 Forge 的 update-electron-app（限开源 + update.electronjs.org）灵活，私有仓库也能自建。完整接入指南（清单机制、publish 配置、事件、平台要点、常见坑）见 electron-updater。

国内加速

下载辅助二进制（nsis、winCodeSign 等）需镜像：

export ELECTRON_BUILDER_BINARIES_MIRROR=https://npmmirror.com/mirrors/electron-builder-binaries/

下载的 Electron 发行版与辅助二进制缓存在 ~/Library/Caches/electron-builder（macOS）/ %LOCALAPPDATA%\electron-builder\Cache（Windows）/ ~/.cache/electron-builder（Linux），用户级、跨项目复用；可用 ELECTRON_BUILDER_CACHE 改位置。注意它与 npm install electron 的缓存（~/Library/Caches/electron 等，ELECTRON_CACHE）是两层独立目录。详见 07-environment-variables「下载缓存」。

交叉编译

跨平台打包部分可行，但签名/公证受平台限制——正式产物交给 CI 矩阵构建。边界详解见 05-packaging-distribution「关于交叉编译」。

与 Forge 对比

维度	electron-builder	Electron Forge
出身	社区	官方
覆盖范围	仅打包/签名/发布	全流程含脚手架
自动更新	`electron-updater` 内置，更新源多	`update-electron-app`，限开源
配置	yml 声明式	JS 插件式

选型表见 README。

zhaoweiguo 的知识库

目录