人人都会AI编程

31.3 打包相关：图标失效、签名失败、安装报错

更新时间：2026-07-11

打包环节的坑往往集中在“看起来能跑，装到用户机器上就出幺蛾子”。这一节我们聚焦三个最高频的打包故障：图标不生效、代码签名被拒、安装过程报错。全部基于 electron-builder 的常见场景，提供直接可用的排查步骤。

28.3.1 图标失效

现象： 开发时窗口左上角和任务栏图标正常，但打包后的 .exe、.dmg 或 .deb 安装完成后，应用图标要么是默认的 Electron 图标，要么是一团空白。

原因分平台解析：

  • Windows (.ico)

.ico 文件必须包含多个尺寸（至少 256×256、48×48、32×32、16×16），否则系统缩放时找不到匹配尺寸就会回退到默认图标。直接用在线工具把 PNG 转成 .ico 时，若只嵌入一张 256×256 的图，任务栏小图标就会崩。

  • macOS (.icns)

.icns 文件需要标准的图标族。如果只是简单把 PNG 改名成 .icns，打包工具会直接忽略。同理，图标背景未设为透明，会在程序坞上显示难看的白底。

  • Linux (.png 或 setIcon)

Linux 下通常需要在 package.json 的 linux 配置里指定 icon 字段，并且提供符合桌面规范（如 512×512）的 PNG 文件。

快速修复：

  1. 统一用 electron-builder 的图标生成工具。在项目根目录放一个 1024×1024 的 icon.png，然后在 electron-builder 配置中添加 "icon": "build/icon.png"（路径随意，名称习惯叫 icon.png）。electron-builder 会自动为各平台生成所需格式和尺寸。
  2. Windows 手动生成 .ico：用在线工具如 icoconverter.com，上传你的 256×256 PNG，确保勾选所有输出尺寸，再下载 .ico。放入 build 目录，在 win 配置里指定 "icon": "build/icon.ico"。
  3. macOS 手动生成 .icns：安装 iconutil（macOS 自带）。准备一个 icon.iconset 文件夹，放入命名规范的 PNG 切片（icon_16x16.png, icon_32x32.png…），然后用命令 iconutil -c icns icon.iconset 生成 .icns。不想手工，可以用 electron-icon-builder 这个 npm 包一键生成。
  4. 去除缓存：Windows 系统有图标缓存，如果安装后图标仍不更新，可以重建图标缓存。在开发机测试时，先卸载旧版、删除安装目录和快捷方式，再重装。

真实踩坑记录：Windows 下 debug 图标时发现 build/icon.ico 包含的 256×256 图实际是 128×128 拉伸的，导致任务栏图标模糊。解决方法就是保证源图为 256×256 及以上真分辨率。

28.3.2 签名失败

macOS 的代码签名和公证最为严格，Windows 的 Authenticode 签名也常有证书问题。

28.3.2.1 macOS 签名与公证失败

常见错误提示：

  • code object is not signed at all
  • errSecInternalComponent 或 CSSMERR_TP_CERT_REVOKED
  • 公证时被拒：The binary is not signed. 或 The signature does not include a secure timestamp.

排查步骤：

  1. 检查证书是否正确安装。打开“钥匙串访问” → 我的证书，确认你的 Developer ID Application 证书存在且有效，没有红色“此证书已被吊销”字样。
  2. 环境变量。electron-builder 通过环境变量取证书名，通常不用显式配置。但若你有多个 Developer ID 证书，需要在 mac 配置中加入 "identity": "Developer ID Application: Your Name (TEAMID)"。注意不要填错团队 ID。
  3. 开启 hardened runtime。macOS 公证要求启用 Hardened Runtime。在 mac 配置中添加 "hardenedRuntime": true，并通常需要配合 "entitlements": "build/entitlements.mac.plist" 和 "entitlementsInherit": "build/entitlements.mac.plist"。一个最基础的 entitlements 文件只需包含 com.apple.security.cs.allow-unsigned-executable-memory 等 boolean 值。
  4. 时间戳服务器。公证要求签名带安全时间戳。只要没有手动关闭 "timestamp" 选项（默认开启），一般没问题。
  5. 双签名检查。打开终端，对 .app 包执行 codesign -dvvv path/to/yourapp.app，看输出是否包含 Authority=Developer ID Application: ... 和 Timestamp=...。再用 spctl --assess -vvv path/to/yourapp.app 看是否 accepted。

公证 reject 后的具体错误：

  • The binary uses an SDK older than the 10.9 SDK：意味着你的 Electron 版本太低或使用了某种老版原生模块。升级相关依赖。
  • The executable requests the com.apple.security.get-task-allow entitlement：绝对不能在发布包中包含 get-task-allow，这只在开发证书签名下存在。确认你签名的证书是生产证书，且 entitlements 里没有这个字段。

28.3.2.2 Windows 签名失败

典型现象：

  • 安装包运行时 SmartScreen 提示“已阻止此应用以保护你的电脑”。
  • 签名时间戳错误导致数字签名无效。

解决要点：

  • 证书类型：必须使用代码签名证书（Code Signing），不能是 SSL 证书。标准 EV 证书和普通 OV 证书都可，但 EV 证书可立即获得 SmartScreen 信誉，普通证书需要积累下载量。
  • 证书安装：确保证书私钥已导入到构建机器的个人证书存储区，且构建服务（如 CI）有权限访问。
  • electron-builder 配置：使用 win.certificateFile 和 win.certificatePassword（如果是 pfx 文件），或 win.certificateSubjectName（如果从存储区读取）。签名失败时可查看 electron-builder 日志，一般会明示错误原因，如“密码错误”或“找不到证书”。
  • 时间戳服务器：确保 win.rfc3161TimeStampServer 或 win.timeStampServer 配置了可用地址。推荐使用 http://timestamp.digicert.com。
  • 双重签名：如果使用 SHA-256 签名，为了兼容 Windows 7 SP1 以下，可能需要同时指定旧版 SHA-1 时间戳，但现在多数应用已放弃兼容这些系统。

28.3.3 安装报错

这里特指在安装阶段（双击安装包时）出现的错误，而非应用启动后的报错。

Windows NSIS 安装器常见错误

  1. Error launching installer

通常因为安装包损坏或下载不完整。检查文件哈希值，确保服务器传输正确。若是通过 CI 发布，需确保 artifact 上传完整。

  1. 权限不足

NSIS 安装目录如果选择 Program Files，需要管理员权限。electron-builder 默认请求 perMachine: true 会触发 UAC。若改为 perMachine: false 安装到用户目录，则不需管理员权限，但应用会仅对当前用户可见。

  1. 自定义 NSIS 脚本导致安装中断

如果添加了 nsis.include 脚本，里面的语法错误可能静默失败，导致窗口一闪而过。调试方法：手动执行生成的安装 .exe 并加上 /LOG=install.log，查看日志定位脚本错误。

  1. 卸载残留

如果用户已经安装过旧版本，但安装目录被锁定或卸载信息损坏，新安装可能失败。此时可以提示用户手动卸载，或在 NSIS 脚本中包含强制覆盖旧版本的逻辑。

macOS DMG 挂载错误

  • “无法打开，因为它来自身份不明的开发者”：这是没有签名或签名未被系统认可的表现。需要完成签名且通过公证。
  • “文件已损坏”：往往也是签名问题，特别是先签名了但又被修改过。重新进行完整打包签名。
  • DMG 窗口布局不符合预期：你可以在 dmg 配置中指定 background、iconSize 等。如果布局错乱，检查背景图路径是否正确，尺寸是否与 DMG 窗口匹配。

Linux deb/rpm 安装依赖问题

  • 缺少 libXss.so.1 等库：Electron 依赖一些系统库，如 libgtk-3-0、libnotify4、libnss3 等。deb 包可通过 depends 字段声明依赖。检查 package.json 中 linux 的 depends 是否包含了必要项，或者引导用户自行安装。
  • 权限错误：安装 deb 包需要 root 权限。用户应使用 sudo dpkg -i 或 gdebi 安装。

排查打包问题的大原则：优先看构建日志，它会显示图标处理、签名调用、打包脚本执行的每一步。不要一遇到 SmartScreen 就认为 Electron “有问题”，大多数时候只是配置缺失或证书不匹配。按照上述清单逐项检查，通常 10 分钟内就能定位根因。