electron-builder

electron-builder

文档：https://www.electron.build（v26.8.x） 仓库：https://github.com/electron-userland/electron-builder

快速开始

安装：

pnpm add electron-builder -D
pnpm add electron-updater  # If using auto-updates

最简配置（electron-builder.yml）：

appId: com.example.myapp
productName: My App
files:
  - "out/**/*"
  - "package.json"
mac:
  target: dmg
  category: public.app-category.developer-tools
win:
  target: nsis
linux:
  target:
    - AppImage
    - deb
publish:
  provider: github

package.json 中的构建脚本：

{
  "scripts": {
    "build:mac": "electron-builder --mac",
    "build:win": "electron-builder --win",
    "build:linux": "electron-builder --linux",
    "build:all": "electron-builder -mwl",
    "release": "electron-builder --publish always"
  }
}

CLI 参考

electron-builder                    # Build for current platform
electron-builder -mwl              # Build for all platforms
electron-builder --mac dmg         # macOS DMG only
electron-builder --win nsis:ia32   # Windows NSIS 32-bit
electron-builder --linux deb tar.xz
electron-builder --dir             # Unpacked dir (test builds)
electron-builder -p always         # Build and publish

# Architecture flags
--x64  --ia32  --armv7l  --arm64  --universal

# CLI config overrides
-c.extraMetadata.foo=bar
-c.mac.identity=null
-c.nsis.unicode=false

# Publish existing artifacts
electron-builder publish -f dist/*.exe -c electron-builder.yml

发布标志的取值：onTag | onTagOrDraft | always | never

配置

配置文件位置（按顺序检查）：

1. package.json > "build" 键
2. electron-builder.yml（默认，推荐）
3. electron-builder.json / .json5 / .toml
4. electron-builder.config.js / .ts
5. CLI：--config <path>

不要将 JS 配置文件命名为 electron-builder.js——这会与软件包名称冲突。

完整配置选项、文件模式、宏、图标和目录设置： 参见 references/configuration.md

基本配置属性

属性	默认值	说明
appId	com.electron.${name}	**部署后不要更改。**用作捆绑包 ID（macOS）和 AUMID（Windows）。
productName	package.json 名称	显示名称（允许包含空格）
compression	"normal"	测试构建可使用 "store" 以加快速度，发布时可使用 "maximum"
asar	true	将源代码打包到 asar 存档中
files	自动	应用源文件的 Glob 模式
extraFiles	—	复制到 asar 外部的文件（例如原生插件）
extraResources	—	复制到 resources 目录的文件
forceCodeSigning	false	如果未签名则构建失败

文件宏

可用于 artifactName、文件模式和发布 URL： ${arch}、${os}、${platform}、${name}、${productName}、${version}、${channel}、${ext}、${env.VAR_NAME}

默认目标

平台	默认值
macOS	DMG + ZIP
Windows	NSIS
Linux（交叉编译）	Snap + AppImage（x64）
Linux（原生）	Snap + AppImage（当前架构）

代码签名

配置后会自动签名。核心环境变量：

环境变量	说明
CSC_LINK	证书路径/URL/base64（.p12/.pfx）
CSC_KEY_PASSWORD	证书密码
CSC_IDENTITY_AUTO_DISCOVERY	true/false（macOS 钥匙串自动发现）
WIN_CSC_LINK	Windows 证书（从 macOS 进行交叉签名时使用）
WIN_CSC_KEY_PASSWORD	Windows 证书密码

macOS：禁用签名

export CSC_IDENTITY_AUTO_DISCOVERY=false
# Or in config: mac.identity: null
# For ad-hoc (ARM): mac.identity: "-"

macOS：公证

mac:
  hardenedRuntime: true
  notarize: true    # or { teamId: "TEAM_ID" }

需要设置 APPLE_ID、APPLE_APP_SPECIFIC_PASSWORD、APPLE_TEAM_ID 环境变量。

Windows：Azure Trusted Signing

win:
  azureSignOptions:
    publisherName: "CN=Your Company"
    endpoint: "https://eus.codesigning.azure.net"
    certificateProfileName: "your-profile"
    codeSigningAccountName: "your-account"

需要设置 AZURE_TENANT_ID、AZURE_CLIENT_ID、AZURE_CLIENT_SECRET。

完整代码签名参考（CI 设置、证书、EV 证书、跨平台）： 参见 references/code-signing.md

自动更新（electron-updater）

最简设置

// main process
import electronUpdater, { type AppUpdater } from "electron-updater";

export function getAutoUpdater(): AppUpdater {
  const { autoUpdater } = electronUpdater;
  return autoUpdater;
}

const autoUpdater = getAutoUpdater();
autoUpdater.checkForUpdatesAndNotify();

不要调用 setFeedURL()——构建时会自动生成 app-update.yml。

ESM 导入（必需的解决方法）

// CORRECT
import electronUpdater from "electron-updater";
const { autoUpdater } = electronUpdater;

// WRONG (may fail with ESM)
import { autoUpdater } from "electron-updater";

支持自动更新的目标

• macOS：DMG
• Windows：NSIS
• Linux：AppImage、DEB、Pacman（Beta）、RPM

macOS 应用必须经过签名才能自动更新。不支持 Squirrel.Windows。

事件

autoUpdater.on("error", (err) => {});
autoUpdater.on("checking-for-update", () => {});
autoUpdater.on("update-available", (info) => {});
autoUpdater.on("update-not-available", (info) => {});
autoUpdater.on("download-progress", (progress) => {
  // .bytesPerSecond, .percent, .total, .transferred
});
autoUpdater.on("update-downloaded", (info) => {
  autoUpdater.quitAndInstall();
});

调试

import log from "electron-log";
autoUpdater.logger = log;
autoUpdater.logger.transports.file.level = "info";

有关分阶段发布、自定义更新器实例、私有仓库和开发测试： 参见 references/auto-update.md

发布

快速设置 GitHub Releases

publish:
  provider: github
  releaseType: draft

设置 GH_TOKEN 环境变量（具有 repo 范围的个人访问令牌）。

快速设置 S3

publish:
  provider: s3
  bucket: my-bucket-name

设置 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY。

快速设置通用服务

publish:
  provider: generic
  url: https://example.com/releases

手动上传构建产物和 latest.yml。

发布 CLI 行为

条件	默认行为
检测到 CI	onTagOrDraft
CI + 推送了标签	onTag
npm 脚本 release	always

发布渠道

版本决定渠道：1.0.0 = latest，1.0.0-beta.1 = beta

有关所有发布服务（Bitbucket、GitLab、Keygen、Snap Store、Spaces）、工作流和高级配置： 参见 references/publishing.md

平台目标配置

macOS

mac:
  category: public.app-category.developer-tools
  hardenedRuntime: true
  darkModeSupport: true
  target: dmg
  entitlements: build/entitlements.mac.plist
  notarize: true

Windows（NSIS）

nsis:
  oneClick: true              # false for assisted installer
  perMachine: false
  allowToChangeInstallationDirectory: false
  createDesktopShortcut: true
  deleteAppDataOnUninstall: false
  include: build/installer.nsh  # Custom NSIS script
  differentialPackage: true

Linux

linux:
  category: Development
  desktop:
    MimeType: "x-scheme-handler/myapp"
  target:
    - AppImage
    - deb
    - snap

有关所有目标选项（DMG、PKG、MAS、MSI、AppX、Snap、Flatpak、portable、自定义 NSIS 脚本）： 请参阅 references/platform-targets.md

构建钩子

执行顺序：

beforeBuild → beforePack → afterExtract → afterPack → [signing] →
afterSign → artifactBuildStarted → [build] → artifactBuildCompleted →
afterAllArtifactBuild

内联（JS/TS 配置）

module.exports = {
  afterSign: async (context) => {
    if (context.electronPlatformName === "darwin") {
      await notarize(context);
    }
  },
  afterAllArtifactBuild: (result) => {
    return ["/path/to/extra/file"];  // Additional files to publish
  },
};

文件引用（YAML 配置）

beforePack: "./scripts/before-pack.js"
afterSign: "./scripts/notarize.js"

// scripts/notarize.js
exports.default = async function(context) {
  // context: { outDir, appOutDir, packager, electronPlatformName, arch, targets }
};

有关所有钩子、上下文接口和编程 API： 请参阅 references/hooks-and-programmatic.md

常见模式

多平台 CI 构建

# GitHub Actions pattern
mac:
  target:
    - target: dmg
      arch: [x64, arm64]
win:
  target:
    - target: nsis
      arch: [x64, ia32]
linux:
  target:
    - target: AppImage
      arch: [x64, arm64]
    - target: deb
      arch: [x64, arm64]
publish:
  provider: github

包含自动更新和签名的完整配置

appId: com.example.myapp
productName: My App
copyright: Copyright 2024 Example Inc.
asar: true
compression: normal
forceCodeSigning: true

directories:
  output: dist
  buildResources: build

files:
  - "out/**/*"
  - "package.json"

mac:
  target: [dmg, zip]
  hardenedRuntime: true
  notarize: true
  category: public.app-category.developer-tools

win:
  target: nsis

nsis:
  oneClick: false
  perMachine: false
  allowToChangeInstallationDirectory: true

linux:
  target: [AppImage, deb]
  category: Development

publish:
  provider: github

electronUpdaterCompatibility: ">= 2.16"

注意事项

1. 发布后切勿更改 appId——NSIS 会将其用作注册表 GUID
2. 自动更新需要 macOS 签名
3. 在 TypeScript 中使用 electron-updater 需要 ESM 导入变通方案
4. 不要调用 setFeedURL()——系统会自动生成 app-update.yml
5. electron-updater 不支持 Squirrel.Windows——请使用 NSIS
6. Windows 环境变量长度限制为 8192 个字符——如果超出限制，请重新导出不含证书链的证书
7. electron-builder.js 会与软件包名称冲突——请使用其他文件名
8. 在主进程中设置 app.setAppUserModelId(appId)，以启用 Windows 通知