简介：这份资源面向使用 Electron 进行桌面应用打包的开发者，尤其是初次接触 electron-builder 或打包流程时频繁报错的新手。它集中提供了 electron-v8.5.5-win32-x64、nsis-3.0.4.2 与 winCodeSign-2.6.0 三套关键依赖，用于补齐打包环境缺失的运行时、安装包制作工具与代码签名组件，下载后放入本地 electron 缓存目录即可直接调用。压缩包为 7z 格式，整体约 356.44MB，文件以 Electron 运行时二进制、NSIS 安装脚本工具及 Windows 签名相关组件为主，覆盖打包链路中的核心环节。目前已有 1548 人学习下载，说明该组合在解决打包报错方面具有较高参考价值。对于被依赖下载失败、签名工具缺失或 NSIS 配置异常困扰的读者，这份资源能省去逐项排查与手动搜集的时间，帮助快速恢复打包流程，适合作为本地离线依赖库长期留存备用。
1. Electron 打包全家桶：为什么离线环境总在最后一步翻车
做过 Electron 桌面端交付的同行大概都经历过这个场景：开发机上electron-builder跑得飞起，一到客户内网或者 CI 隔离环境，构建脚本就卡在下载环节——electron-v8.5.5-win32-x64.zip拉不下来、nsis-3.0.4.2.7z超时、winCodeSign-2.6.0.7z直接 404。这不是网络玄学，而是 Electron 打包链路里三个核心依赖的缓存机制在作祟。所谓「Electron 打包全家桶」，指的就是把 Electron 运行时二进制、NSIS 安装包制作工具、Windows 代码签名工具链这三样东西提前备齐，让构建过程完全脱离外网。这套方案解决的是离线构建、内网交付、构建可复现三个刚需，适合需要给客户交付安装包、或者在隔离网络中做 CI/CD 的桌面端团队。下面按「先搞懂每个组件干什么 → 再动手配缓存 → 最后排坑」的顺序拆开讲。
2. 三件套各自管什么：electron、nsis、winCodeSign 的职责边界
2.1 electron-v8.5.5-win32-x64 是运行时不是安装器
很多人第一次接触会混淆：electron-v8.5.5-win32-x64.zip是 Electron 官方预编译的运行时二进制包，解压后得到electron.exe、chrome_100_percent.pak、icudtl.dat、resources/default_app.asar等文件。它的作用是作为你应用的「宿主」——你写的业务代码最终跑在这个运行时里。electron-builder在打包时会把你的app.asar塞进这个运行时目录，再改个名字变成YourApp.exe。
版本号v8.5.5对应 Electron 8.x 系列，win32-x64表示 Windows 64 位目标平台。注意这个包和 npm 上的electron包不是一回事：npm 包只是个下载器，安装时会去 GitHub Release 拉对应的二进制 zip。离线环境要备的就是这个 zip 本身。
2.2 nsis-3.0.4.2 负责生成 Windows 安装向导
NSIS（Nullsoft Scriptable Install System）是 Windows 平台老牌安装包制作工具。electron-builder默认用 NSIS 生成.exe安装程序，支持自定义安装路径、创建快捷方式、注册卸载信息、增量更新等。nsis-3.0.4.2是electron-builder内置依赖的特定版本，它不是一个标准 NSIS 发行版，而是经过裁剪、附带nsis-resources和若干插件的定制包。
为什么版本要卡这么死？因为electron-builder的 NSIS 脚本模板（.nsh文件）和 NSIS 版本强耦合。你换成 NSIS 3.08 或者 3.10，可能编译时报Invalid command: nsExec或者宏展开失败。所以离线缓存必须用electron-builder期望的那个版本号。
2.3 winCodeSign-2.6.0 是签名工具链不是证书
winCodeSign-2.6.0.7z里面装的是signtool.exe、osslsigncode、时间戳服务相关工具，以及一些辅助 DLL。它的职责是给最终的.exe安装包和内部的YourApp.exe做数字签名，让 Windows SmartScreen 不弹「未知发布者」警告。
这里有个常见误解：以为下了winCodeSign就有证书了。不是的。它只是工具，真正的代码签名证书（.pfx或.p12）需要你自己从 CA 机构购买或申请。winCodeSign解决的是「有证书但没工具签名」的问题，不是「没证书怎么签名」。
2.4 三者的依赖关系与缓存目录结构
electron-builder在构建时会按顺序查找这三个包。默认缓存路径在 Windows 上是%LOCALAPPDATA%\electron-builder\Cache，Linux/macOS 上是~/.cache/electron-builder。目录结构大致如下：
electron-builder/Cache/ ├── electron/ │ └── electron-v8.5.5-win32-x64.zip ├── nsis/ │ └── nsis-3.0.4.2/ │ └── nsis-3.0.4.2.7z └── winCodeSign/ └── winCodeSign-2.6.0/ └── winCodeSign-2.6.0.7z注意nsis和winCodeSign目录下还有一层同名子目录，这是electron-builder解压后的结构。如果你手动放缓存，必须把.7z文件放在正确层级，否则它还是会去下载。
提示：不同
electron-builder版本对缓存路径的解析逻辑略有差异，建议先用一次在线构建，观察它实际下载到了哪里，再照葫芦画瓢做离线缓存。
3. 离线缓存怎么配：从手动放置到环境变量接管
3.1 手动放置缓存文件的完整步骤
最直接的办法是手动把三个包放到缓存目录。以 Windows 为例，假设你已经从能联网的机器上拿到了这三个文件：
# 假设三个文件已下载到 D:\offline-packages\ # 目标缓存根目录 set CACHE_ROOT=%LOCALAPPDATA%\electron-builder\Cache # 1. 放置 electron 运行时 mkdir "%CACHE_ROOT%\electron" copy D:\offline-packages\electron-v8.5.5-win32-x64.zip "%CACHE_ROOT%\electron\" # 2. 放置 nsis mkdir "%CACHE_ROOT%\nsis\nsis-3.0.4.2" copy D:\offline-packages\nsis-3.0.4.2.7z "%CACHE_ROOT%\nsis\nsis-3.0.4.2\" # 3. 放置 winCodeSign mkdir "%CACHE_ROOT%\winCodeSign\winCodeSign-2.6.0" copy D:\offline-packages\winCodeSign-2.6.0.7z "%CACHE_ROOT%\winCodeSign\winCodeSign-2.6.0\"逻辑说明：electron-builder在需要某个依赖时，会先检查缓存目录下是否存在对应文件。如果存在且校验通过（部分版本会校验文件大小或哈希），就直接解压使用；否则触发下载。所以手动放置的关键是「路径和文件名完全匹配」。
参数说明：%LOCALAPPDATA%是 Windows 用户级环境变量，通常指向C:\Users\你的用户名\AppData\Local。如果你在 CI 环境用系统账户跑构建，这个路径可能不同，建议显式设置ELECTRON_BUILDER_CACHE环境变量覆盖。
3.2 用 ELECTRON_BUILDER_CACHE 统一缓存位置
在 CI 或多人协作场景，把缓存放在项目目录下更可控。electron-builder支持通过ELECTRON_BUILDER_CACHE环境变量指定缓存根目录：
# Linux/macOS export ELECTRON_BUILDER_CACHE=$(pwd)/.electron-cache # Windows CMD set ELECTRON_BUILDER_CACHE=%CD%\.electron-cache # Windows PowerShell $env:ELECTRON_BUILDER_CACHE = "$PWD\.electron-cache"设置后，electron-builder会在这个目录下创建electron/、nsis/、winCodeSign/子目录。你只需要把三个离线包按同样结构放进去即可。这样做的好处是缓存跟着项目走，换机器时直接拷贝整个.electron-cache目录就能复用。
3.3 在 package.json 里锁定版本避免漂移
光有缓存还不够，必须确保electron-builder请求的版本号和你缓存的版本号一致。在package.json里显式声明：
{ "build": { "electronVersion": "8.5.5", "win": { "target": "nsis" }, "nsis": { "oneClick": false, "allowToChangeInstallationDirectory": true } }, "devDependencies": { "electron": "8.5.5", "electron-builder": "22.10.5" } }逻辑说明：electronVersion字段告诉electron-builder去缓存里找哪个版本的 Electron 运行时。如果不写，它会从electron包的package.json里读版本号，但离线环境下electron包安装时可能已经失败，所以显式写死更稳妥。
参数说明：electron-builder的版本也要锁。不同版本的electron-builder内置的 NSIS 和 winCodeSign 版本号可能不同。比如 22.x 系列通常对应nsis-3.0.4.2和winCodeSign-2.6.0，而 23.x 可能就变了。锁死electron-builder版本是保证缓存匹配的前提。
3.4 验证缓存是否生效的检查命令
配置完后，跑一次构建，观察日志里是否还有downloading字样：
# 开启 debug 日志 set DEBUG=electron-builder npx electron-builder --win --x64如果输出里出现downloading或者cannot download，说明缓存没命中。此时检查三点：文件路径是否精确匹配、文件名是否完全一致（包括.7z后缀）、文件是否完整（部分下载的残包会导致解压失败）。
4. 避坑指南：离线打包最常见的五类翻车
4.1 缓存文件放对了但构建仍去下载
现象：明明把electron-v8.5.5-win32-x64.zip放进了Cache/electron/，构建日志还是显示downloading electron-v8.5.5-win32-x64.zip。
原因：electron-builder在下载前会检查缓存文件是否存在，但部分版本还会校验文件大小。如果你从非官方渠道拿到的 zip 被重新压缩过，大小不一致，它就会认为缓存无效。
解决：用官方 Release 的原始文件，不要二次压缩。如果实在拿不到原始文件，可以尝试在electron-builder配置里关闭校验（不推荐，有风险），或者用electron-builder的--config参数指定electronDownload.cache路径。
4.2 nsis 解压后缺少插件导致编译失败
现象：NSIS 编译阶段报Invalid command: nsExec或Plugin not found: ShellExecAsUser。
原因：nsis-3.0.4.2.7z解压后应该包含Plugins/目录和Include/目录。如果你手动解压时只取了部分文件，或者用了错误的解压工具导致目录结构丢失，插件就找不到了。
解决：不要手动解压。让electron-builder自己解压。你只需要放.7z文件，它会解压到同级目录。如果你已经手动解压了，删掉解压出来的目录，只留.7z文件，重新构建。
4.3 winCodeSign 在非管理员权限下签名失败
现象：构建到最后签名步骤报SignTool Error: Access is denied或The specified user does not have a valid profile。
原因：winCodeSign里的signtool.exe在签名时需要访问证书存储区，非管理员账户或者没有加载用户配置文件的 CI 服务账户可能没有权限。
解决：在 CI 环境用管理员权限运行构建，或者改用osslsigncode（winCodeSign包里也带了）做签名。osslsigncode不依赖 Windows 证书存储，直接读.pfx文件，更适合自动化环境。
4.4 缓存目录权限导致解压失败
现象：Linux CI 上构建报EACCES: permission denied, mkdir '/root/.cache/electron-builder'。
原因：CI 容器里以非 root 用户运行，但HOME指向/root，没有写权限。
解决：显式设置ELECTRON_BUILDER_CACHE到一个当前用户有写权限的目录，比如$HOME/.electron-cache或项目目录下的.cache。
4.5 版本号写错导致缓存永远不命中
现象：缓存目录里明明有nsis-3.0.4.2，但构建日志显示在下载nsis-3.0.4.2，反复循环。
原因：electron-builder内部请求的 NSIS 版本号可能带后缀，比如nsis-3.0.4.2实际请求的是nsis-3.0.4.2.7z，但缓存目录名写成了nsis-3.0.4.2而文件放成了nsis-3.0.4.2.zip。文件名和目录名必须和electron-builder期望的完全一致。
解决：开DEBUG=electron-builder看它具体请求的 URL 和文件名，然后照着改缓存文件名。
5. 进阶技巧：把全家桶做成可复用的离线构建镜像
5.1 用 Docker 封装离线构建环境
如果团队有多台构建机，或者需要频繁在隔离环境重建 CI，把三件套和 Node 环境一起打进 Docker 镜像是最省事的做法。下面是一个最小化的 Dockerfile 示例：
FROM node:14-windowsservercore-ltsc2019 # 设置缓存目录 ENV ELECTRON_BUILDER_CACHE=C:\electron-cache # 拷贝离线包 COPY offline-packages/ C:\offline-packages\ # 按 electron-builder 期望的结构放置缓存 RUN mkdir C:\electron-cache\electron && \ copy C:\offline-packages\electron-v8.5.5-win32-x64.zip C:\electron-cache\electron\ && \ mkdir C:\electron-cache\nsis\nsis-3.0.4.2 && \ copy C:\offline-packages\nsis-3.0.4.2.7z C:\electron-cache\nsis\nsis-3.0.4.2\ && \ mkdir C:\electron-cache\winCodeSign\winCodeSign-2.6.0 && \ copy C:\offline-packages\winCodeSign-2.6.0.7z C:\electron-cache\winCodeSign\winCodeSign-2.6.0\ WORKDIR /app逻辑说明：基于node:14-windowsservercore-ltsc2019镜像，自带 Node 14 和 Windows Server Core 环境。把离线包拷贝进去后，在镜像构建阶段就完成缓存目录的初始化。后续跑构建时，electron-builder直接命中缓存，不再需要外网。
参数说明：node:14-windowsservercore-ltsc2019这个基础镜像体积较大（约 5GB），但兼容性最好。如果对镜像体积敏感，可以换node:14-alpine配合 Wine 跑 Windows 构建，但 Wine 环境下签名和 NSIS 编译的坑更多，不建议新手尝试。
5.2 用校验脚本确保缓存完整性
在 CI 流水线里加一步校验，避免缓存文件损坏导致构建随机失败：
#!/bin/bash # check-cache.sh CACHE_DIR="${ELECTRON_BUILDER_CACHE:-$HOME/.cache/electron-builder}" check_file() { local filepath="$1" local min_size="$2" if [ ! -f "$filepath" ]; then echo "MISSING: $filepath" exit 1 fi local actual_size=$(stat -c%s "$filepath" 2>/dev/null || stat -f%z "$filepath") if [ "$actual_size" -lt "$min_size" ]; then echo "CORRUPTED: $filepath (size $actual_size < $min_size)" exit 1 fi echo "OK: $filepath" } check_file "$CACHE_DIR/electron/electron-v8.5.5-win32-x64.zip" 50000000 check_file "$CACHE_DIR/nsis/nsis-3.0.4.2/nsis-3.0.4.2.7z" 1000000 check_file "$CACHE_DIR/winCodeSign/winCodeSign-2.6.0/winCodeSign-2.6.0.7z" 1000000逻辑说明：check_file函数检查文件是否存在，以及文件大小是否超过一个保守的下限。Electron 运行时 zip 通常 50MB 以上，NSIS 和 winCodeSign 的 7z 包通常 1MB 以上。如果文件大小异常，说明下载不完整或文件损坏。
参数说明：min_size的值需要根据实际文件调整。建议先用ls -l看一下正常文件的大小，然后取一个略低于正常值的数作为阈值。这样既能拦住明显损坏的文件，又不会因为版本差异误报。
5.3 一个我踩过的坑：缓存目录名大小写敏感
在 Linux 上构建 Windows 包时，electron-builder请求的缓存路径可能是winCodeSign（驼峰），但如果你手动创建目录时写成了wincodesign（全小写），Linux 文件系统区分大小写，就会找不到。Windows 上不区分大小写所以没事，一到 Linux CI 就翻车。这个坑我花了两个小时才定位到，血泪经验就是：缓存目录名严格照抄electron-builder日志里的路径，别自己发挥。
5.4 验证离线构建是否真正脱离外网
最后一步验证：把构建机的网络断开（或者用防火墙规则屏蔽 GitHub 和 npm registry），跑一次完整构建。如果构建成功，说明缓存配置到位。如果失败，看日志里请求了哪个 URL，那就是还没缓存到的依赖。常见遗漏包括：app-builder-bin（electron-builder的辅助二进制）、7za.exe（解压工具）等。这些通常在electron-builder安装时就随 npm 包一起下来了，但如果你用的是--no-optional安装，可能会缺。
我现在的习惯是：每接一个新项目，先在有网环境跑一次完整构建，把%LOCALAPPDATA%\electron-builder\Cache整个目录打包存档，后面所有离线环境都从这个存档初始化。这样比逐个文件排查省事得多。希望帮到你。
本文还有配套的精品资源，点击获取
