彻底解决 npm 安装 Electron 失败的问题

为什么 npm install electron 总是失败

执行 npm install --save-dev electron 经常卡住，最终报错：

npm error code ETIMEDOUT
npm error errno ETIMEDOUT
...
RequestError: connect ETIMEDOUT 185.199.108.133:443

或：

Error: connect ECONNREFUSED 0.0.0.0:443

原因不是 npm 包本身的问题，而是 Electron 的安装脚本会在 npm install 完成后，从 GitHub Releases 下载一个几十到一百多 MB 的二进制压缩包（electron-vX.X.X-linux-x64.zip 或 electron-vX.X.X-win32-x64.zip）。

这个下载地址是：

https://github.com/electron/electron/releases/download/vX.X.X/...

在国内，GitHub Releases 的下载速度极慢甚至完全不可达，导致安装超时失败。

方案一：使用 cnpm（推荐快速解决）

cnpm 是淘宝/阿里维护的 npm 客户端，使用 npmmirror.com 作为源，同时代理了 Electron 的二进制文件：

# 1. 全局安装 cnpm，指向国内镜像
npm install -g cnpm --registry=https://registry.npmmirror.com

# 2. 用 cnpm 安装 Electron
cnpm install --save-dev electron

cnpm 会自动将 Electron 二进制的下载地址替换为 https://npmmirror.com/mirrors/electron/，速度快且稳定。

方案二：配置 ELECTRON_MIRROR 环境变量

不想换 npm 客户端的话，只需告诉 Electron 安装脚本去哪里下载二进制：

# Linux / macOS
export ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"
npm install --save-dev electron

# Windows PowerShell
$env:ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"
npm install --save-dev electron

# Windows CMD
set ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
npm install --save-dev electron

或者在项目根目录创建 .npmrc 文件，永久生效：

# .npmrc
electron_mirror=https://npmmirror.com/mirrors/electron/

方案三：全局配置 .npmrc（推荐持久化）

在用户主目录的 ~/.npmrc（或 %USERPROFILE%\.npmrc）中添加：

registry=https://registry.npmmirror.com
electron_mirror=https://npmmirror.com/mirrors/electron/
electron_builder_binaries_mirror=https://npmmirror.com/mirrors/electron-builder-binaries/

之后所有项目的 npm install electron 都会走国内镜像，无需额外操作。

方案四：用 bun 或 pnpm（更现代的方式）

bun 和 pnpm 都内置了更好的网络处理，配合镜像更稳定：

# bun（自动用更快的并发下载）
bun add -d electron
# 配合环境变量
ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ bun add -d electron

# pnpm（同样支持 .npmrc 的 electron_mirror）
pnpm add -D electron

方案五：手动下载后安装

网络实在不稳定时，可以手动下载二进制再安装：

# 1. 查看当前要安装的 Electron 版本
cat node_modules/electron/package.json | grep '"version"'
# 或者先 npm install，让它下载 package，失败后手动补充二进制

# 2. 从 npmmirror 手动下载对应版本的 zip
# https://npmmirror.com/mirrors/electron/v28.2.0/electron-v28.2.0-linux-x64.zip

# 3. 将下载的 zip 放入缓存目录
mkdir -p ~/.electron
cp electron-v28.2.0-linux-x64.zip ~/.electron/

# 4. 设置 ELECTRON_SKIP_BINARY_DOWNLOAD 并重新安装（让脚本直接用缓存）
ELECTRON_SKIP_BINARY_DOWNLOAD=1 npm install --save-dev electron

常见报错速查

报错	原因	解决方案
`ETIMEDOUT`	GitHub 下载超时	配置 `ELECTRON_MIRROR`
`ECONNREFUSED`	连接被拒绝	代理未配置或镜像地址错误
`checksum mismatch`	缓存文件损坏	清除 `~/.electron` 或 `~/.cache/electron` 重新下载
`Unsupported platform`	平台/架构不支持	检查 Node 和系统架构是否匹配
Permission denied	全局安装权限不足	用 `sudo` 或修复 npm 全局目录权限

验证安装成功

# 检查 electron 是否可执行
./node_modules/.bin/electron --version
# 输出示例：v28.2.0

# 或通过 npx
npx electron --version

延伸：electron-builder 也有类似问题

如果你使用 electron-builder 打包，它也会下载额外的工具链（nsis、7za 等）。同样在 .npmrc 中配置：

electron_builder_binaries_mirror=https://npmmirror.com/mirrors/electron-builder-binaries/