彻底解决electron安装失败的问题

1、背景

最近在初始化一个新的桌面端项目时，准备引入 Electron 作为核心框架。本以为是一个简单的 npm install electron -D 过程，结果却卡在安装阶段迟迟无法完成。

这其实是前端开发中一个非常经典的问题，尤其是在国内网络环境下，Electron 的二进制包下载失败几乎是每个 Electron 开发者都会遇到的“第一道坎”。

2、发现问题

在执行安装命令后，终端通常会抛出类似以下的错误信息：

1
2> electron@40.0.0 postinstall /path/to/project/node_modules/electron
3
4> node install.js
5
6RequestError: connect ETIMEDOUT 20.205.243.166:443
7
8    at ClientRequest.<anonymous> (/path/to/project/node_modules/got/dist/source/core/index.js:970:11)
9
10    at Object.onceWrapper (node:events:628:26)
11
12    ...
13
14    at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1494:16) {
15
16  message: 'connect ETIMEDOUT 20.205.243.166:443',
17
18  code: 'ETIMEDOUT',
19
20  ...
21
22}
23

或者有时会遇到校验和不匹配（Checksum mismatch）的问题，提示文件已存在但无法打开。

3、查找原因

为什么 Electron 这么难装？

通过查看 node_modules/electron/install.js 的源码可以发现，Electron 的 npm 包实际上只是一个“壳”，真正的核心二进制文件（几十兆甚至上百兆）是在安装时的 postinstall 阶段，通过一个名为 @electron/get 的工具从 GitHub Releases 上下载的。

由于 GitHub 的 Release 文件通常托管在 AWS S3 上，国内访问极其不稳定，经常会导致连接超时或下载中断。

4、根本原因

归结起来主要有三点：

1. 网络拦截：默认下载地址 github.com 在国内访问受限。

2. DNS 污染：导致无法正确解析下载服务器的真实 IP。

3. 缓存污染：之前的下载尝试失败，留下了一个损坏的临时文件，导致后续即便网络好了也会因校验失败而报错。

5、解决方案

为了彻底解决这个问题，我总结了以下三个层级的方案，按推荐程度排序：

方案一：修改 .npmrc 配置文件（最推荐，一劳永逸）

在项目根目录下创建或修改 .npmrc 文件，直接指定 Electron 的镜像源。这种方式可以随代码仓库同步，确保团队其他成员也不会卡住。

1
2# 使用淘宝镜像源
3
4electron_mirror=https://npmmirror.com/mirrors/electron/
5
6# 如果是极旧版本的 electron，可能需要手动指定版本号目录
7
8# electron_custom_dir=v30.0.0 
9

方案二：命令行临时指定环境变量

如果你只是临时安装一个 Demo，不想修改配置文件，可以在安装命令前加上环境变量：

1
2# macOS/Linux
3
4ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ npm install electron -D
5
6# Windows (PowerShell)
7
8$env:ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"; npm install electron -D
9

方案三：手动下载并注入缓存（终极方案）

如果镜像源也挂了，或者你即使配置了国内镜像源，下载还是蜗牛速度，可以采取手动安装（我目前就是遇到下载速度贼慢，最后用这个方式解决了）：

1. 手动下载：去 淘宝镜像站 手动下载对应版本的 zip 包（例如 electron-v30.0.0-darwin-arm64.zip）。
2. 计算该安装包需要放置的上层目录的Hash值 我通过开启@electron/get包的debug模式，找到electron的Hash目录的组织规律，这样，你收工下载electron的包，比如你要求下载的版本包是：

https://github.com/electron/electron/releases/download/v30.5.1/electron-v30.5.1-darwin-arm64.zip

那么你直接按照这个规律进行拼装下载链接，下载到本地，然后把这个下载链接转变成一个新的字符串：https://github.com/electron/electron/releases/download/v30.5.1

其实也就是去掉后面的zip的路径，然后到SHA256上加密得到一串Hash值，之后就可以到第三个步骤的缓存目录新建Hash目录，把zip包复制过去

比如https://github.com/electron/electron/releases/download/v30.5.1的SHA256是3fc8b100354a78e048c5a36cd89ea3c5ae19222fb41a8b533daedaae0879fe84

3. 放置缓存目录：将下载好的压缩包放入系统的缓存文件夹：

   • macOS: ~/Library/Caches/electron/

   • Linux: ~/.cache/electron/

   • Windows: %LOCALAPPDATA%\electron\cache

4. 重新执行安装：此时执行 pnpm install，脚本会检测到本地缓存，直接跳过下载阶段。

这个过程发现electron的install.js的这段代码有问题： 因为electron的npm包在30版本之后压根就没有path.txt文件，否则我直接把安装包解压到这里的dist目录也是一样的效果的。

4、参考

• # 安装指导