简介对于使用 Electron 构建桌面应用的开发者而言在 Windows 平台下进行打包时常因本地缓存目录缺少关键依赖而构建失败本资源正好解决了这一问题。资源标题所示的“全家桶”包含 electron-v8.5.5-win32-x64、nsis-3.0.4.2 和 winCodeSign-2.6.0 三个核心组件其中 Electron 8.5.5 负责应用运行时NSIS 3.0.4.2 用于生成安装程序WinCodeSign 2.6.0 承担代码签名与校验三者配合 electron-builder 等工具可形成完整闭环显著降低因依赖不齐、版本不匹配或网络下载超时导致的打包失败概率。压缩包以 7z 格式发布整体约 356.44MB内部按 Electron 官方 Cache 目录结构整理解压后放入 C:\Users\XXX\AppData\Local\electron\Cache 即可被构建工具自动识别免去逐个项目手动配置的繁琐。资源已有 1548 人学习使用对刚入门打包的初学者、经常重装电脑或维护多台构建机的开发者来说是一份省时省力的离线备件也能为团队统一构建环境提供有效备份。整个压缩包保留了各组件原始版本与目录结构便于多环境重复部署和版本追溯特别适合离线环境或网络状况不佳的场景这套组合解决了大多数 Electron 应用在 Windows 分发时的环境痛点。1. electron 打包全家桶三个缓存文件才是安装包产线的真正主力Electron 打包慢十次有八次不是编译慢而是卡在下载上。你看到的标题里那三个文件——electron-v8.5.5-win32-x64、nsis-3.0.4.2、winCodeSign-2.6.0——就是 electron-builder 打 Windows 安装包时最依赖的“全家桶”。它们分别对应 Electron 运行时、NSIS 安装程序框架和 Windows 代码签名工具默认落在本地缓存目录里。把它们一次对齐、缓存好本机和 CI 出安装包的速度能从十几分钟压到两三分钟。这个方向适合被打包等待折磨过、又不想每次在网络波动上下注的 Electron 桌面应用开发者。2. 从 electron-v8.5.5-win32-x64 到 exeelectron-builder 的完整打包链路2.1 electron-builder 到底在做什么下载、组装、压缩三步先拆解链路。Electron 应用本身是跑在 Chromium 和 Node 之上的应用要变成 Windows 上能双击运行的 exe需要经历把应用资源打成 app.asar拿一个与平台匹配的 Electron 运行时也就是标题里的 electron-v8.5.5-win32-x64.zip把 asar 放进去形成绿色版的 win-unpacked 目录再把 win-unpacked 用 7z 压缩成 app-64.7z随后调用 NSIS 生成 setup.exe 安装引导这里的 nsis-3.0.4.2 就是安装器外壳最后调用 winCodeSign-2.6.0 里的签名工具给 exe 和安装包签名。我一般会把 7z 压缩和 NSIS 生成这两步放在一起看NSIS 安装器并不是直接拷贝 win-unpacked 里的所有文件而是把压缩后的 7z 嵌入安装器用户在安装时边解压边写入。这也是为什么最后产物里能看到一个体积很大的 setup.exe但它内部其实是“引导器 压缩包 卸载器”三件套。这五步里真正需要网络的是 2、4、5。第 2 步尤其容易被忽略electron-v8.5.5-win32-x64.zip 的体积通常在 80MB 以上如果你的 package.json 里声明的是 8.5.5但本地之前的打包用到的是别的版本electron-builder 会按版本号重新抓旧缓存不会被复用。所以别以为“上次打包成功了这次就快”版本号一变之前的下载全作废。2.2 最小配置跑通打包package.json 与 build 字段常见做法是直接在 package.json 里写 build 配置命令用 electron-builder不需要额外引入 webpack 之类的构建链。如果你的渲染层不需要打包成单一 bundleelectron-builder 自己就能负责拷贝资源和 asar 封装需要 webpack 的是纯前端构建场景那是在跑 electron-builder 之前的事。我也顺手对比过 pyinstaller 和 pyside 的打包流程electron-builder 更像个黑匣子——它不把每一步暴露成 spec 文件而是通过固定参数把三个缓存文件抓齐版本一不对就重新下载。最小配置长这样{ name: demo-app, version: 1.0.0, main: src/main/index.js, scripts: { pack: electron-builder --win nsis --x64 }, devDependencies: { electron: 8.5.5, electron-builder: ^20.44.4 }, build: { appId: com.example.demo, productName: DemoApp, directories: { output: release }, files: [ src/**/*, package.json ], win: { target: [nsis], icon: build/icon.ico }, nsis: { oneClick: false, allowToChangeInstallationDirectory: true } } }执行 npm run pack 之后electron-builder 会先检查 devDependencies 里 electron 版本是 8.5.5就去缓存目录找 electron-v8.5.5-win32-x64.zip找到就直接解压复用找不到就下载。接着按 win.target 里的 nsis 去取 nsis-3.0.4.2 和 winCodeSign-2.6.0。这三个一旦就位后面的组装基本是本地计算不再依赖网络。关键参数说明main 指向的是 Electron 主进程入口electron-builder 不负责编译主进程它只是把这个文件作为 app.asar 的入口。files 数组用来控制哪些目录进安装包。把 node_modules 漏掉是新手常犯的错误纯 JS 依赖会被收进 asar但原生模块需要单独处理。win.target 写成数组将来要同时出 nsis 和 zip 时可以写 [nsis, zip]全家桶会分别跑两遍不算多余。2.3 版本号对齐为什么全家桶必须是一个整体electron 8.5.5 对应 win32-x64nsis 固定 3.0.4.2winCodeSign 固定 2.6.0。这三者不是随便拼的。electron-builder 的不同版本会对某一组 nsis / winCodeSign 版本有绑定关系日志里能看到 “Downloading nsis-3.0.4.2” 这样的字样。我自己的经验是只要升级 electron-builder 大版本nsis 和 winCodeSign 往往也会跟着换标题里这一组是 20.x 时代很常见的组合。缓存目录长这样文件默认缓存目录electron-v8.5.5-win32-x64.zip%LOCALAPPDATA%\electron\Cachensis-3.0.4.2.7z%LOCALAPPDATA%\electron-builder\Cache\nsiswinCodeSign-2.6.0%LOCALAPPDATA%\electron-builder\Cache\winCodeSign注意 %LOCALAPPDATA% 在不同 Windows 账号下不一样而且 electron 二进制的缓存目录和 electron-builder 自己的缓存目录是两个地方。看到这三个路径就能理解“打包全家桶”里的“全家桶”其实指的是只要把这三样东西手工放对位置electron-builder 就以为你已经下载过了直接进入组装环节。这也是后面离线打包思路的基础。3. nsis-3.0.4.2安装包外壳的参数调优与 7 个常用配置3.1 认识 nsis 在 electron-builder 里的角色模板与脚本NSIS 是一个 Windows 安装程序制作工具electron-builder 没有自己写安装器而是把 NSIS 当外壳。nsis-3.0.4.2 这个 7z 包里包含 NSIS 主程序、Stubs、Plugins还有 electron-builder 专用的模板脚本。打包时 electron-builder 用这些模板生成一个安装器 exe安装器在用户机器上做的事包括解压 app-64.7z、写注册表卸载信息、创建开始菜单快捷方式、显示安装向导界面。它并不是把 install.nsi 原样拷贝。electron-builder 的模板是固定的通过配置项拼出一段 .nsi 脚本想自己写 .nsi 也可以但只能在 build.nsis.include 里指定一个自定义脚本片段让模板去 include 它。真的从头写一个完整的 NSIS 脚本在 electron-builder 体系里基本用不上也容易把打包流程带偏。winform 打包成安装程序时常用的 VS 自带部署和 Electron 走 NSIS 是两条完全不同的路线不要把两者混着看。3.2 安装向导的关键参数oneClick、perMachine、安装目录先看一段我常用的 nsis 配置nsis: { oneClick: false, perMachine: false, allowElevation: true, allowToChangeInstallationDirectory: true, createDesktopShortcut: true, createStartMenuShortcut: true, shortcutName: DemoApp, artifactName: ${productName}-Setup-${version}.${ext}, installerHeaderIcon: build/installer-icon.ico, deleteAppDataOnUninstall: false, include: build/nsis-custom.nsi }参数说明oneClick默认 true点一下就直接装不显示向导。改成 false 才走“下一步 / 下一步”的安装向导页。perMachine是否全机器安装。false 表示装到当前用户目录也就是 %LOCALAPPDATA%\Programstrue 需要管理员权限装到 Program Files。allowElevation配合 perMachine 使用false 时不弹 UAC我一般保持 true避免以后切到 perMachine 时被权限卡住。allowToChangeInstallationDirectory不写的话用户安装时看不到目录选择页。artifactName输出安装包的名字。默认是${productName} Setup ${version}.exe我习惯用${productName}-Setup-${version}.${ext}CI 脚本好按模式匹配文件。deleteAppDataOnUninstall卸载时是否清掉用户数据。这个默认 false建议不要开用户卸载应用不意味着要删掉本地数据。include自定义脚本入口后面单独说。从实战角度最影响安装体验的是 oneClick 和 perMachine 的组合。oneClicktrue 时安装过程没有任何选择页用户连目录都改不了oneClickfalse 时才能把“安装选项”页面释放出来。产品经理要求“用户可选安装目录”时必须把 oneClick 关掉同时把 allowToChangeInstallationDirectory 打开缺一个都不生效。3.3 中文环境、快捷方式与卸载行为Electron 打包在中文 Windows 下最常见的两个问题第一安装路径。productName 如果带中文生成的默认安装目录就会带中文。electron-builder 对中文目录本身没限制但如果 app.asar 里有原生 C 模块某些模块对路径编码敏感会出现模块加载失败。我一般把内部用的 name 保持英文productName 按产品对外名称走安装体验交给 installerLanguages 去控制系统语言。第二快捷方式残留。shortcutName 决定开始菜单和桌面的名字同一台机器如果装过多个版本旧的快捷方式可能不会被卸载器清干净菜单里出现两个“DemoApp”。这种情况多数来自卸载时新老版本混装卸载器按新版本的 uninstall 注册表去处理旧目录结果删不干净。我会先让测试机做一次完整卸载再重装确认不是安装器覆盖逻辑的问题再去追快捷方式来源。NSIS 的卸载器还会调用 electron-builder 生成的 uninstaller 脚本删除开始菜单目录和快捷方式。如果你的版本升级后卸载找不到旧版本多半是安装目录里新旧版本文件混着建议先卸载再重装别直接覆盖。3.4 一个自定义脚本的常见用法include 自定义脚本一般是改安装完成后的动作比如写注册表或提示重启。一个最小示例!macro customInstall WriteRegStr HKCU Software\DemoApp installed true !macroendcustomInstall 是 electron-builder 的 NSIS 模板向外暴露的宏不需要你懂整个 NSIS只要照着这个宏往里塞指令就行。把这个文件路径填到 include 里构建时模板会自动拼进去。NSIS 脚本里路径有空格要加引号用到 $INSTDIR 时要小心转义这些错误在 electron-builder 日志里看不到出错时非常难查。我一般只在需要写注册表、改 shell 行为时才加 include平时的安装目录控制都靠 JSON 配置不加脚本少一个黑盒就少一份风险。4. winCodeSign-2.6.0代码签名与 SmartScreen 信任链实操4.1 winCodeSign 装了什么、何时被调用winCodeSign-2.6.0 是 electron-builder 用于 Windows 代码签名的一组工具集合里面是 signtool.exe 之类的可执行文件和配套 dll。打包 Windows 目标时electron-builder 会先解压 winCodeSign 到缓存把证书文件和密码塞给它的 signtool对 win-unpacked 里的 exe、dll 以及最终的 setup.exe 逐个签名。很多人以为签名只针对 setup.exe其实 electron-builder 会对多个文件签一遍主进程 exe、渲染进程里可能存在的 dll、升级用的 exe最后一个才是安装器外壳。签名顺序先内后外一旦顺序反了Windows 会认为安装包内部组件来源不一致SmartScreen 反而更容易跳警告。4.2 自动签名配置CSC_LINK 与 CSC_KEY_PASSWORDelectron-builder 的签名不写在 package.json 里而是走环境变量CSC_LINK证书文件路径可以是 pfx、p12也可以是一个 base64 编码的字符串。CSC_KEY_PASSWORD证书私钥密码。在 Windows PowerShell 里这样设$env:CSC_LINK C:\certs\company.pfx $env:CSC_KEY_PASSWORD your-password npx electron-builder --win nsis --x64在 Git Bash 里export CSC_LINK/c/certs/company.pfx export CSC_KEY_PASSWORDyour-password npx electron-builder --win nsis --x64electron-builder 在打包流程的 sign 阶段读这两个变量。如果 CSC_LINK 没设置它会跳过签名直接产出未签名的 exe打包不报错。这就是为什么新手没配证书也能正常出安装包只是装上后 SmartScreen 会跳提示。CSC_LINK 另一个反直觉的点是它接受路径也接受证书内容的 base64。CI 里不想把 pfx 塞进代码仓库就先对证书做 base64 编码再放到环境变量base64 -w 0 company.pfx把输出的长字符串填给 CSC_LINK。注意 base64 字符串里不能有换行否则 signtool 解析会失败这是 CI 上常见的签名翻车点。4.3 手动签名兜底什么时候绕过 electron-builder 的签名有一种场景你想用脚本统一签名而不是让 electron-builder 每次自动签。比如证书在远程签名服务上或者 electron-builder 自动签名时不支持你指定的时间戳服务器。这时候可以先关掉自动签名打包完成后自己调用 signtool。在 package.json 的 build.win 里加win: { sign: ./build/sign.js }sign.js 是一个导出函数的模块electron-builder 会调用它代替内置签名逻辑。更简单的做法是保持默认自动签名等打包完成后对最终 exe 再用 signtool 签一次。但同一个文件签两次不会覆盖之前的签名如果你的两次证书链不一致SmartScreen 反而更乱。我建议用不到自定义签名时别碰 sign 字段等真正需要时再动手。4.4 时间戳服务器与双重签名签名参数对照表signtool 的核心参数长这样signtool sign /f company.pfx /p your-password \ /tr http://timestamp.digicert.cn /td sha256 /fd sha256 \ /a DemoApp-Setup-1.0.0.exe参数作用常见坑/f指定证书文件路径含空格要用引号包住/p证书密码密码带特殊字符时注意转义/trRFC3161 时间戳服务器地址必须用支持 sha256 的服务器/td时间戳摘要算法不写时部分 Windows 版本认不出/fd文件摘要算法sha256 是常见选择/a自动选择最佳证书机器上证书多时建议用 /sha1 精确指定时间戳的意义是让签名在证书过期后仍然有效。只签文件名、不写 /tr签名本身有效但 Windows 会显示“数字签名无效或时间戳不准”。我一般在打包机上固定一个时间戳服务器避免每次打包时来回换。签名完成后用下面的命令验证signtool verify /v /pa DemoApp-Setup-1.0.0.exe输出里能看到签名者、证书链、时间戳状态。如果证书链完整SmartScreen 的提示会轻很多如果验证结果是“证书链不完整”说明证书是自签的或者中间证书没装全需要先解决证书本身的问题。5. 打包全家桶避坑记录缓存、版本不匹配、签名失败5.1 卡在 Downloading electron-v8.5.5-win32-x64.zip现象执行 electron-builder 后日志停在 “Downloading electron-v8.5.5-win32-x64.zip” 十几分钟不动或者反复下到一半就失败。原因electron-builder 默认从 GitHub release 拉 Electron 二进制源站响应慢加上 zip 体积大很容易超时。不是项目配置的问题是下载环节扛不住波动。解决先把 zip 手动下载回来放到 %LOCALAPPDATA%\electron\Cache 目录下。文件命名必须严格是 electron-v8.5.5-win32-x64.zip后缀不一致 electron-builder 认不出来。另一个做法是给 Electron 二进制设置镜像地址export ELECTRON_MIRRORhttps://npmmirror.com/mirrors/electron/设置后 electron-builder 会自动从镜像地址拼出完整下载路径。注意这个镜像只覆盖 Electron 运行时不影响 nsis 和 winCodeSign 的下载源后两者走的是另一处二进制镜像不同 electron-builder 版本的变量名略有差异以日志里展示的下载 URL 为准。我养成的习惯是先看日志里的 Downloading 后面跟的 URL用它判断当前走的是哪个源手动下载时也让下载工具保存的文件名与 URL 最后一段完全一致。5.2 nsis 版本不匹配报错现象报错 “Cannot find nsis-3.0.4.2” 或 “Downloading nsis-3.0.4.2 failed”。也有反过来本地缓存里有 nsis-3.0.4.2但 electron-builder 要的是别的版本。原因electron-builder 的版本决定它要哪一个 nsis。本地缓存里同时躺着多个版本时electron-builder 只认自己要的那一个。缓存目录被换位置、权限不对也会导致它找不到。解决直接清空对应缓存目录让它重新下载Remove-Item -Recurse -Force $env:LOCALAPPDATA\electron-builder\Cache\nsis npx electron-builder --win nsis --x64如果内网能下载也可以手动放置 nsis-3.0.4.2.7z。手动放缓存要同时检查两样东西7z 包本身以及它解压后的目录。electron-builder 解压到一半失败时会留下残缺目录这时候即使 7z 文件在构建照样报错。清空重下最省事别在这种地方节省时间。5.3 签名失败退出代码 1现象打包进行到 sign 阶段后失败日志出现 “Exit code: 1”后面跟一行 SignTool Error 或 crypt32 相关提示但不会直接告诉你密码错没错。原因winCodeSign 里的 signtool 拿到证书后读不了私钥。常见四条路证书密码写错、证书文件本身不是 pfx/p12 而是一堆 DER 文件、证书已过期、缓存里的 winCodeSign 解压不全。解决先不看 electron-builder 日志直接拿 winCodeSign 里的 signtool 试一次 $env:LOCALAPPDATA\electron-builder\Cache\winCodeSign\winCodeSign-2.6.0\windows-10\signtool.exe sign /f C:\certs\company.pfx /p guess-password /tr http://timestamp.digicert.cn /td sha256 /fd sha256 C:\demo.exe不带 electron-builder 的包装signtool 给出的错误信息直白得多密码错会说 “The password you specified is incorrect”文件格式不对会说 “Cannot open the file”。血泪经验证书文件别放在含中文或空格的路径下signtool 对这类路径的兼容性不稳定先复制到 C:\certs 再签名能少踩一半的坑。5.4 SmartScreen“未知发布者”但签名验证通过现象打包成功签名也验证通过但用户机器上 Windows 仍然提示“Windows 已保护你的电脑”红色界面。原因SmartScreen 的信誉不是只看“有没有签名”还看签名的根证书是否在系统信任区、证书是否 EV、这个 exe 在信誉库里有没有历史记录。新证书、普通 OV 证书第一次出现提示是正常的。解决先确认签名是不是真的进了安装包signtool verify /v /pa DemoApp-Setup-1.0.0.exe看到签发者是机构证书就可以把锅归到信誉积累而不是打包链路。要消除这种提示通常只能上 EV 证书并确保安装包经过了带时间戳的 sha256 签名。如果是自签证书SmartScreen 怎么调优都会拦。另一个可查的点是时间戳如果签名时 /td 没写 sha256老时间戳服务可能签出 sha1 时间戳新版系统上验证状态会显示“可重新签名时间”的灰色状态用户看到就是不信任。把 /tr /td 两个参数补齐很多“签名有效但体验差”的问题会消失。5.5 清理盘符后打包速度从 3 分钟退回 30 分钟现象某天清理 C 盘剩余空间后打包从 3 分钟变成 30 分钟日志里重新出现 Downloading 全家桶。原因%LOCALAPPDATA% 在 C 盘electron 和 electron-builder 的缓存目录被扫盘工具清掉了。三个文件一旦没了electron-builder 不认识本地还有副本只好重新下载。解决在专用打包机和 CI 上把缓存目录迁出 C 盘。我自己的打包机把缓存目录指向 D 盘重装系统后只需要把 D 盘里的目录拷回来。具体做法下一章给出核心是让缓存目录离开系统盘。不要以为这是偶然很多人第一次清理系统盘时就把 electron-builder 的缓存当成垃圾清掉了回头打包慢得像换了一台机器这真的不是玄学。6. 让全家桶一次到位离线缓存与打包热迁移技巧先说一个被验证过很多次的结论electron-builder 的下载慢问题八成能用缓存预置解决。做法是把三个文件固定成一个可复制的目录新机器和 CI 上直接放过去不用每次等它重下。第一步把现有缓存里的三件套归档到一起。以 Windows 打包机为例$cacheRoot $env:LOCALAPPDATA Copy-Item $cacheRoot\electron\Cache\electron-v8.5.5-win32-x64.zip D:\electron-pack-cache Copy-Item $cacheRoot\electron-builder\Cache\nsis\nsis-3.0.4.2.7z D:\electron-pack-cache Copy-Item $cacheRoot\electron-builder\Cache\winCodeSign D:\electron-pack-cache -Recurse理论上只要这三样版本对齐新机器上把文件放到对应位置electron-builder 就会直接复用网络波动不再影响产线。为了不让系统盘清理误伤我会把缓存根目录迁出 C 盘$env:ELECTRON_BUILDER_CACHE D:\electron-pack-cache设置后 electron-builder 优先认这个目录作为缓存根目录。注意这个环境变量控制的是 nsis 和 winCodeSign 的位置Electron 二进制的缓存位置由 ELECTRON_CACHE 控制两个变量一起设全家桶才不会散。我踩过一次教训把 ELECTRON_BUILDER_CACHE 指向了一个带中文的路径某些版本解析时把路径转成 URL中文被解析成乱码缓存命中失败构建回退到重新下载。后来一律用纯英文路径。另外别把 electron 缓存和 electron-builder 缓存叠在同一个子目录两个包对目录层级的要求不同放错层级的结果是没被识别日志照样去下载看起来像是玄学其实就是路径层级不对。验证缓存是否命中不需要等打包结束。看日志前面的下载环节如果在命令输出里找不到 Downloading electron / Downloading nsis / Downloading winCodeSign 三项而是直接进入 Building 阶段说明全家桶命中。我最后想分享的习惯是把“缓存是否命中”当成打包速度问题的第一排查点每次打包前先看这一项比反复换下载源更靠得住。希望帮到你。本文还有配套的精品资源点击获取