Electron 与 node-gyp 二进制下载失败：安装卡住、ETIMEDOUT、找不到预编译包怎么办

做桌面应用或者用到原生模块的前端同学，经常遇到同一种情况：把 npm 源换成国内镜像后，几百个依赖几十秒就装完了，唯独卡在「node_modules/electron: Running postinstall script」不动，十几分钟后报「RequestError: connect ETIMEDOUT」；或者安装 better-sqlite3、bcrypt 这类带原生代码的包时，终端刷出一串「gyp ERR!」，最后一行写着下载 Node 头文件超时。

原因在于这些包的安装分两段：第一段从 npm 源下载包本身，镜像源能加速；第二段由安装脚本自己去下载二进制文件，Electron 去 GitHub Releases 下载几十 MB 的压缩包，node-gyp 去 Node 官网下载头文件，prebuild 系列工具去 GitHub 下载预编译好的原生模块。第二段完全不经过 npm 源，换镜像对它无效。弄清每个工具从哪里下载、读哪个环境变量，问题就能逐个解决。各工具的配置项名称会随版本变化，以官方文档为准。

各工具的二进制下载来源

这张表的关键是「默认来源」一列：大部分都指向 GitHub Releases，而 GitHub 的发布文件实际托管在另一组下载域名上，在国内经常速度很低或连接超时。解决思路只有两种：要么让下载走线路，要么把下载地址改成可用的镜像。前者对所有工具都有效，后者需要逐个配置，但配好之后团队里每个人都能受益。

从卡住到装好：分步操作

• 第一步：先把网络线路准备好。连上刺猬VPN并确认终端能访问 GitHub，执行 curl -I https://github.com 能返回状态码即可；自定义用户名和密码即可匿名注册，不需要邮箱、不需要手机号，免费节点永久免费、不限流量、不限速，适合先验证二进制文件能否下载；
• 第二步：让终端走代理。系统代理模式下，很多命令行工具不会自动读取系统设置，需要在当前终端设置 HTTPS_PROXY 环境变量指向客户端的本地代理端口，Electron 的下载器还需要额外设置 ELECTRON_GET_USE_PROXY=1 才会读取代理变量；
• 第三步：或者改用镜像下载 Electron。设置环境变量 ELECTRON_MIRROR 指向可信的镜像地址，镜像目录结构与官方不同时，再用 ELECTRON_CUSTOM_DIR 指定版本目录格式，设置后重新执行安装；
• 第四步：清理半成品。安装中断后先删除 node_modules/electron 目录，必要时清掉 Electron 的缓存目录，Windows 在本地应用数据的 electron\Cache 下，macOS 与 Linux 在用户缓存目录的 electron 下，再重新安装；
• 第五步：处理 node-gyp 头文件。执行安装时加上 --dist-url 参数指向 Node 头文件的镜像目录，或者在项目里配置 disturl；也可以提前执行 node-gyp install 单独下载头文件，确认成功后再装依赖；
• 第六步：检查编译环境。Windows 需要安装 Visual Studio 生成工具并勾选「使用 C++ 的桌面开发」，还需要 Python；macOS 需要执行 xcode-select --install 安装命令行工具；Linux 需要 build-essential 与 Python；
• 第七步：处理预编译包。prebuild-install 输出「No prebuilt binaries found」时会退回本地编译，这本身不是错误，只要编译环境齐全就能装上；不想编译就让下载走线路，或按该包文档配置镜像；
• 第八步：配置写进项目。把镜像相关的环境变量写进团队文档或 CI 配置，新版 npm 对 .npmrc 里不认识的配置项会给出警告，环境变量比写进 .npmrc 更稳妥；
• 第九步：CI 环境单独处理。服务器上没有桌面客户端，可以在 CI 里配置缓存，把 Electron 与 node-gyp 的缓存目录保存下来，第二次构建就不必重新下载。

按现象排查

安装日志很长，真正有用的往往是最后十几行。把报错复制下来，按关键词对照下面的现象。需要更详细的信息时，安装命令加上详细日志参数，能看到每个文件具体是从哪个地址下载的。

• 卡在 electron 的 postinstall 很久：Electron 压缩包正在从 GitHub 下载，速度太低，让下载走线路或设置镜像；
• RequestError: connect ETIMEDOUT：连接下载地址超时，终端没有走代理，检查 HTTPS_PROXY 与 ELECTRON_GET_USE_PROXY；
• HTTPError: Response code 404：镜像地址或目录格式写错，下载器拼出的路径在镜像上不存在，核对 ELECTRON_CUSTOM_DIR；
• 「Electron failed to install correctly」：上次安装中断留下了不完整的文件，删除 node_modules/electron 后重装；
• gyp ERR! 中出现下载头文件超时：node-gyp 去 Node 官网下载失败，用 --dist-url 指向镜像或让终端走线路；
• gyp ERR! find VS：Windows 没有安装 C++ 生成工具，按第六步安装后重开终端；
• gyp ERR! find Python：系统找不到 Python，安装后确认命令行里能执行 python；
• electron-builder 打包时下载失败：打包工具需要的组件也来自 GitHub，设置 ELECTRON_BUILDER_BINARIES_MIRROR 或让下载走线路。

线路与镜像怎么选

镜像的好处是配置一次、全队受益，坏处是镜像同步可能滞后，新版本刚发布时镜像上还没有。走线路则对所有工具一视同仁，不需要逐个配置，但每台机器都要设置好终端代理。比较稳妥的做法是两者结合：常用的 Electron 与 node-gyp 配镜像，偶发的其他二进制下载走线路。刺猬VPN的「不限速」只表示不对账号设速率上限，实际下载速度取决于本地网络与节点负载。

Windows、macOS 与 Linux 的差别

Windows 是原生模块问题最多的平台：编译依赖 Visual Studio 生成工具，安装包有好几个 GB，路径里有中文或空格时部分旧版工具会出错，项目尽量放在纯英文路径下。PowerShell 设置环境变量的写法是 $env:变量名=值，只对当前窗口有效；想长期生效就在系统环境变量里添加，改完要重开终端。

macOS 的问题集中在芯片架构：Apple 芯片的电脑需要 arm64 版本的 Electron 与原生模块，用了 x64 版本的 Node 会导致下载错误的架构，执行 node -p process.arch 确认当前架构。Linux 服务器最常见的问题是缺少编译工具与 Python，以及没有图形界面时 Electron 无法启动测试，CI 里需要虚拟显示环境。三个平台的缓存目录也不同，清缓存前先确认路径。

团队与持续集成的统一做法

一个人的电脑配好了，不代表整个团队都能顺利安装。比较好的做法是把下载相关的配置集中放在项目里：在说明文档中写清楚需要设置哪些环境变量、镜像地址是什么、遇到报错先看哪一节；在安装脚本前面加一段检查，如果环境变量没设置就给出提示，而不是让新同事对着几百行日志发呆。

持续集成环境更要提前规划。每次构建都重新下载 Electron 与 Node 头文件，既慢又容易失败，在流水线里把这几个缓存目录作为缓存保存下来，按锁文件的哈希值作为缓存键，依赖不变时直接复用，构建时间可以缩短一大截。构建服务器在海外时，二进制下载通常很快，反而是国内镜像可能更慢，这时不要照搬本地的镜像配置，按服务器所在位置分别设置。

版本锁定与升级时的注意事项

Electron 的大版本升级很频繁，每次升级都会重新下载运行时，原生模块也要针对新的 Electron 版本重新编译，这一步由 electron-rebuild 或打包工具自动完成，同样会去下载头文件。升级前先确认镜像上已经同步了新版本，再修改版本号，否则会出现本地装好了、同事那边报 404 的情况。

锁文件一定要提交到仓库，保证每个人装到的是同一个版本，避免有人装到刚发布、镜像尚未同步的版本。原生模块升级前先查看它的发布页是否提供了对应 Electron 版本的预编译包，没有的话就要准备好编译环境，或者暂缓升级。遇到无法解释的安装错误时，删除锁文件重新生成往往不是好办法，先清缓存、再重装，问题通常更容易定位。

和其他开发工具的分工

Electron 的二进制下载只是依赖安装的一部分，npm、pnpm、yarn、pip、Maven 等包管理器的镜像源怎么切换、各自的配置文件写在哪里，见 开发包管理器镜像源配置指南，先把包本身的下载加速，再处理二进制这一段。

二进制文件大多托管在 GitHub Releases 上，GitHub 克隆慢、Releases 下载慢、raw 文件打不开的原因与处理办法，见 GitHub 访问加速指南。终端走代理的设置方法在那篇里也有详细说明，和本文的步骤可以直接配合使用。

常见报错速查表

高频问答

• 问：换了 npm 镜像为什么 Electron 还是慢？答：Electron 运行时由安装脚本从 GitHub 单独下载，不经过 npm 源，需要单独配置镜像或走线路；
• 问：开了客户端终端还是超时？答：很多命令行工具不读系统代理，要在终端里设置 HTTPS_PROXY，Electron 还需 ELECTRON_GET_USE_PROXY；
• 问：镜像配置写在 .npmrc 里可以吗？答：可以，但新版 npm 会对不认识的配置项发出警告，环境变量更稳妥；
• 问：No prebuilt binaries found 是不是安装失败？答：不一定，它会退回本地编译，编译环境齐全就能装上；
• 问：Apple 芯片的电脑装错架构怎么办？答：确认 Node 是 arm64 版本，删除 node_modules 后重新安装；
• 问：团队里每个人都要配置吗？答：镜像变量写进项目文档或脚本，CI 配缓存，新成员照着做即可。

让依赖安装一次成功

Electron 与 node-gyp 二进制下载失败，根源是安装脚本绕过了 npm 镜像，直接去 GitHub 和 Node 官网下载。先看日志判断是哪个工具在下载，再选择让终端走线路或者配置对应的镜像变量，安装中断后记得清理半成品与缓存，原生模块再补齐编译环境，基本就能一次装好。

刺猬VPN采用 HTTPS+AES 加密传输，支持自定义用户名和密码匿名注册，不需要邮箱和手机号；免费节点永久免费、不限流量、不限速，适合偶尔装一次依赖；时长套餐有效期内不限流量、不限速，适合每天开发、频繁切换版本的同学，客户端带断线保护与按域名分流，一个账号支持多设备同时在线。各工具的配置项以官方文档为准，实际可用性取决于当前网络环境。