electron-builder 是目前社区中最主流的 Electron 应用打包与分发工具。它能够将你的应用打包成 Windows、macOS、Linux 三端的安装包，并支持自动更新、代码签名、NSIS/MSI/DMG 等多种格式。配置方式通常是在 package.json 中增加 "build" 字段，或使用独立的 electron-builder.yml 文件。
16.2.1 最小化配置
最简单的配置只需要指定应用 ID 和基础信息，其余都会走默认值：
// package.json
{
"name": "my-app",
"version": "1.0.0",
"main": "main.js",
"build": {
"appId": "com.example.myapp",
"productName": "My App",
"directories": {
"output": "dist"
},
"files": [
"main.js",
"preload.js",
"dist/**/*"
]
}
}appId：应用的唯一标识符，必须设置，一般为反向域名格式。productName：显示在桌面和安装程序中的名称，为空则使用name。directories.output：打包输出目录，默认为dist。files：告诉 electron-builder 需要打包哪些文件。通常会指定主进程脚本、预加载脚本以及你前端构建产物的文件夹。
16.2.2 多平台差异化配置
可以在 build 中使用 win、mac、linux 字段分别定制不同平台的安装包行为：
{
"build": {
"appId": "com.example.myapp",
"win": {
"target": [
{ "target": "nsis", "arch": ["x64", "ia32"] }
],
"icon": "assets/icon.ico",
"artifactName": "${productName}-Setup-${version}.${ext}"
},
"mac": {
"target": "dmg",
"icon": "assets/icon.icns",
"category": "public.app-category.productivity",
"hardenedRuntime": true,
"entitlements": "build/entitlements.mac.plist"
},
"linux": {
"target": ["AppImage", "deb"],
"icon": "assets/icon.png",
"category": "Utility"
}
}
}Windows 配置要点
target：常用nsis（生成 .exe 安装程序），也可以是portable（免安装版）、msi（企业部署）或zip。icon：必须为.ico格式，建议包含 256x256 尺寸。artifactName：定义输出文件名模板，变量productName、version、ext等可用。
macOS 配置要点
target：常用dmg（磁盘映像）或mas（Mac App Store）。icon：必须是.icns格式。category：用于 Mac App Store 上架时的分类。hardenedRuntime：启用 Apple 的运行时加固，如果计划公证则必须为true。entitlements：指定权限文件，用于申请摄像头、麦克风、文件系统访问等特殊权限。
Linux 配置要点
target：支持AppImage（通用格式）、deb（Debian/Ubuntu）、rpm（Fedora）、snap等。icon：PNG 格式，建议 512x512。category：符合桌面入口规范（如Utility、Development、Office）。
16.2.3 自动更新常用配置
electron-builder 内置了对 electron-updater 的支持，只需配置 publish 字段：
{
"build": {
"publish": [
{
"provider": "generic",
"url": "https://my-update-server.com/releases"
}
]
}
}provider 支持 github、s3、generic 等多种后端。配置好后，打包时会自动生成 latest.yml（Windows/macOS）或 latest-linux.yml 等更新元数据文件，配合 electron-updater 即可实现应用内自动检测更新。
16.2.4 多语言与个性化安装界面（仅 NSIS）
使用 NSIS 时，可以定制安装程序的语言、界面样式：
{
"win": {
"target": "nsis",
"nsis": {
"oneClick": false,
"perMachine": true,
"allowToChangeInstallationDirectory": true,
"installerLanguages": ["en_US", "zh_CN"],
"license": "assets/license.txt",
"shortcutName": "My App"
}
}
}oneClick：设置为false会显示安装向导，否则为静默一键安装。perMachine：为true安装到Program Files，需要管理员权限。allowToChangeInstallationDirectory：允许用户选择安装目录。installerLanguages：安装程序语言包列表。
16.2.5 高级文件过滤与额外资源
有时你需要将某些额外的本地文件夹或二进制程序一同打包：
{
"build": {
"extraResources": [
{
"from": "bin/ffmpeg",
"to": "ffmpeg",
"filter": ["**/*"]
}
],
"asarUnpack": [
"node_modules/some-native-module/**"
]
}
}extraResources：将指定文件/文件夹复制到打包后的资源目录中（位于 asar 包外部），便于通过process.resourcesPath访问。asarUnpack：把某些模块从 asar 归档中提取出来，通常用于包含原生二进制模块的场景（如sqlite3）。
16.2.6 实际项目推荐配置结构
为了便于维护，大型项目通常会把 electron-builder 配置抽离为单独文件，并利用环境变量区分开发与发布构建：
# electron-builder.yml
appId: com.example.myapp
productName: My App
copyright: Copyright © 2025 Example Inc.
directories:
output: release
buildResources: build
files:
- main.js
- preload.js
- dist/**/*
win:
target: nsis
icon: build/icon.ico
mac:
target: dmg
icon: build/icon.icns
hardenedRuntime: true
entitlements: build/entitlements.mac.plist
linux:
target: AppImage
icon: build/icon.png
publish:
provider: generic
url: https://update.example.com/download然后在 package.json 中指定配置文件：
{
"scripts": {
"pack": "electron-builder --dir",
"dist": "electron-builder",
"dist:win": "electron-builder --win",
"dist:mac": "electron-builder --mac",
"dist:linux": "electron-builder --linux"
}
}实用建议：
- 为避免误打包
node_modules中的开发依赖，在package.json中将所有仅构建时使用的工具放入devDependencies，electron-builder 默认只打包dependencies。 - 如果使用 monorepo 或 pnpm，可能需要调整
nodeGypRebuild和npmRebuild选项以确保原生模块正确编译。 - 在 CI 中构建时，确保对应的操作系统环境满足签名要求（macOS 需要钥匙串访问权限，Windows 需要证书文件和相关密码）。
掌握这些核心配置后，你就可以将 Electron 应用转化成一个标准、可发布的桌面安装程序。下一小节将介绍代码签名与实际分发流程，让你的应用能够安全、顺畅地抵达用户手中。