Electron 打包与分发
electron-builder 配置、三平台产物、图标与签名准备。
Key Pointselectron-builder 一条命令产出各平台安装包；签名不是可选项，未签名的应用会被系统拦下。
安装 electron-builder
Bash
npm install --save-dev electron-builder配置
JSON
{
"name": "my-app",
"version": "1.0.0",
"main": "main.js",
"scripts": {
"dist": "electron-builder",
"dist:win": "electron-builder --win",
"dist:mac": "electron-builder --mac",
"dist:linux": "electron-builder --linux"
},
"build": {
"appId": "com.example.myapp",
"productName": "My App",
"directories": { "output": "release" },
"files": ["main.js", "preload.js", "dist/**/*", "!**/*.map"],
"asar": true,
"win": {
"target": [{ "target": "nsis", "arch": ["x64"] }],
"icon": "build/icon.ico"
},
"nsis": {
"oneClick": false,
"allowToChangeInstallationDirectory": true,
"createDesktopShortcut": true
},
"mac": {
"target": ["dmg"],
"icon": "build/icon.icns",
"category": "public.app-category.productivity"
},
"linux": {
"target": ["AppImage", "deb"],
"icon": "build/icon.png",
"category": "Utility"
}
}
}产物
Bash
npm run dist:winText
release/
├── My App Setup 1.0.0.exe ← Windows 安装包
├── My App-1.0.0.AppImage ← Linux 免安装
├── My App-1.0.0.dmg ← macOS 磁盘映像
└── win-unpacked/ ← 解压后的目录版nsis is the Windows installer wizard, portable a single-file build, AppImage the Linux portable format. End users want installers; internal distribution is easier with portables.
图标
| Platform | Format | Size |
|---|---|---|
| Windows | .ico | 256×256 起，内含多种尺寸 |
| macOS | .icns | 512×512 起 |
| Linux | .png | 512×512 |
Prepare a 1024×1024 PNG and let electron-icon-builder generate all three. A bad icon fails packaging with only "invalid icon" as the message.
签名
Bash
# macOS：需要 Apple Developer 证书
export CSC_LINK=/path/to/cert.p12
export CSC_KEY_PASSWORD=yourpassword
# Windows：需要代码签名证书
set CSC_LINK=C:\path\to\cert.pfx
set CSC_KEY_PASSWORD=yourpassword| Platform | Unsigned consequence |
|---|---|
| Windows | SmartScreen 警告「未知发布者」 |
| macOS | Gatekeeper 直接拒绝，提示「已损坏」 |
| Linux | 一般不受限 |
On macOS an unsigned, un-notarised app shows "the app is damaged and can't be opened" — not a permission prompt, it simply will not launch. Signing plus notarisation is unavoidable.
常见打包问题
- 产物太大 —— 检查
dependencies是否混进了开发依赖 - 白屏 ——
files漏了资源，或用了打包后失效的绝对路径 - 原生模块报错 —— 需要
electron-rebuild或asarUnpack - 只出当前平台 —— 交叉编译有限制，最好用 CI 分平台构建
JSON
{
"build": {
"asarUnpack": ["**/*.node", "resources/**"]
}
}Native modules (.node) cannot load from inside an asar and must be asarUnpacked. Forget it and every call fails with Cannot find module after packaging.
安装 electron-builder
Bash
npm install --save-dev electron-builder配置
JSON
{
"name": "my-app",
"version": "1.0.0",
"main": "main.js",
"scripts": {
"dist": "electron-builder",
"dist:win": "electron-builder --win",
"dist:mac": "electron-builder --mac",
"dist:linux": "electron-builder --linux"
},
"build": {
"appId": "com.example.myapp",
"productName": "My App",
"directories": { "output": "release" },
"files": ["main.js", "preload.js", "dist/**/*", "!**/*.map"],
"asar": true,
"win": {
"target": [{ "target": "nsis", "arch": ["x64"] }],
"icon": "build/icon.ico"
},
"nsis": {
"oneClick": false,
"allowToChangeInstallationDirectory": true,
"createDesktopShortcut": true
},
"mac": {
"target": ["dmg"],
"icon": "build/icon.icns",
"category": "public.app-category.productivity"
},
"linux": {
"target": ["AppImage", "deb"],
"icon": "build/icon.png",
"category": "Utility"
}
}
}产物
Bash
npm run dist:winText
release/
├── My App Setup 1.0.0.exe ← Windows 安装包
├── My App-1.0.0.AppImage ← Linux 免安装
├── My App-1.0.0.dmg ← macOS 磁盘映像
└── win-unpacked/ ← 解压后的目录版nsis 是 Windows 的安装向导，portable 是免安装单文件，AppImage 是 Linux 的免安装格式。给普通用户就用安装包，给企业内网分发用免安装版更省事。
图标
| 平台 | 格式 | 尺寸 |
|---|---|---|
| Windows | .ico | 256×256 起，内含多种尺寸 |
| macOS | .icns | 512×512 起 |
| Linux | .png | 512×512 |
准备一张 1024×1024 的 PNG，用 electron-icon-builder 一次生成三平台图标。图标不合格会导致安装包制作失败，而且错误信息只说「invalid icon」。
签名
Bash
# macOS：需要 Apple Developer 证书
export CSC_LINK=/path/to/cert.p12
export CSC_KEY_PASSWORD=yourpassword
# Windows：需要代码签名证书
set CSC_LINK=C:\path\to\cert.pfx
set CSC_KEY_PASSWORD=yourpassword| 平台 | 不签名的后果 |
|---|---|
| Windows | SmartScreen 警告「未知发布者」 |
| macOS | Gatekeeper 直接拒绝，提示「已损坏」 |
| Linux | 一般不受限 |
macOS 上未签名 + 未公证的应用，用户看到的是「应用已损坏，无法打开」——不是权限提示，是直接打不开。必须签名并
notarize，这一步没有绕过的办法。常见打包问题
- 产物太大 —— 检查
dependencies是否混进了开发依赖 - 白屏 ——
files漏了资源，或用了打包后失效的绝对路径 - 原生模块报错 —— 需要
electron-rebuild或asarUnpack - 只出当前平台 —— 交叉编译有限制，最好用 CI 分平台构建
JSON
{
"build": {
"asarUnpack": ["**/*.node", "resources/**"]
}
}原生模块（.node）不能从 asar 里加载，必须 asarUnpack 出来。忘了这一步，打包后一调用就报 Cannot find module。