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

Electron 的安装是前端工程师最常碰壁的环节之一，尤其是在国内网络环境下。本文系统梳理根因，并提供 2024-2025 年最新有效的解决方案，覆盖 npm、pnpm、Yarn、Bun 以及 CI/CD 场景。

Electron 安装为何特殊

两阶段安装机制

安装 Electron 不像普通 npm 包那样只下载 JavaScript 代码。它分两个阶段：

阶段一：npm 下载 electron 包本身（只有几 KB 的 JS 代码和配置）

阶段二：postinstall 脚本运行 electron/install.js，从 GitHub Releases 下载预编译的二进制文件（electron-vX.X.X-platform-arch.zip），大小约 100~300 MB。

node_modules/electron/
  install.js         ← postinstall 运行这个
  path.txt           ← 记录已下载的二进制路径
  dist/
    electron         ← 这才是真正的 Electron 可执行文件
    resources/
    ...

国内网络根因

预编译二进制文件托管在 https://github.com/electron/electron/releases。由于众所周知的原因，GitHub Releases 的下载在国内极不稳定：

• 下载速度极慢（可能 10KB/s 甚至更低）
• 频繁超时（默认超时 30s）
• 随机中断

这导致 npm install 在 node_modules/.cache 阶段挂起，最终以如下错误结束：

RequestError: connect ETIMEDOUT 140.82.114.4:443
  at ClientRequest.<anonymous> (node_modules/got/source/request-as-event-emitter.js:178:14)
  ...

或

× [Electron] Downloading Electron... failed
  Error: read ECONNRESET

三种解决方案

方案一：.npmrc 镜像（最推荐）

在项目根目录（或用户主目录）创建/修改 .npmrc：

# 设置 Electron 镜像
ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/

# 也可以设置 npm registry 镜像
registry=https://registry.npmmirror.com

npmmirror.com（原淘宝镜像，现官方维护）是目前最稳定的国内镜像，同步 GitHub Releases 通常在几分钟内。

全局设置（推荐放在 ~/.npmrc）：

npm config set ELECTRON_MIRROR https://npmmirror.com/mirrors/electron/
npm config set registry https://registry.npmmirror.com

验证设置：

npm config get ELECTRON_MIRROR
# 输出：https://npmmirror.com/mirrors/electron/

方案二：环境变量

不想改 .npmrc？可以通过环境变量临时设置：

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

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

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

也可以在单次命令中指定（跨平台推荐用 cross-env）：

npx cross-env ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ npm install

方案三：手动缓存

如果网络实在无法访问，可以手动下载二进制文件并放到缓存目录。

1. 确定需要的版本和文件名：

# 查看 package.json 中的 electron 版本
cat node_modules/electron/package.json | grep '"version"'
# 例如："version": "32.0.0"

# 文件名格式
# electron-v{version}-{platform}-{arch}.zip
# 例如：electron-v32.0.0-win32-x64.zip
#       electron-v32.0.0-linux-x64.zip
#       electron-v32.0.0-darwin-arm64.zip

2. 手动下载（可通过有代理的机器或手机热点下载）：

从 https://npmmirror.com/mirrors/electron/v32.0.0/ 下载对应平台的 zip 文件。

3. 放到缓存目录：

# Windows
%LOCALAPPDATA%\electron\Cache
# macOS
~/Library/Caches/electron/

# Linux
~/.cache/electron/

# 具体路径可以通过 electron-download 查看：
node -e "const p = require('path'); console.log(p.join(require('os').homedir(), '.cache', 'electron'))"

将下载的 zip 文件直接放入以上目录，重新运行 npm install，install.js 会检测到本地缓存并跳过下载。

pnpm 的对应方案

pnpm 使用相同的环境变量：

# .npmrc（pnpm 也读取）
ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/

# 或环境变量
ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ pnpm install

pnpm 特有的配置（~/.pnpmfile.cjs 或 .pnpmrc）：

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

Yarn 的对应方案

Yarn Classic (v1)：

# 全局设置
yarn config set ELECTRON_MIRROR https://npmmirror.com/mirrors/electron/

# .yarnrc（项目级）
ELECTRON_MIRROR "https://npmmirror.com/mirrors/electron/"

Yarn Berry (v2+)：

# .yarnrc.yml
npmRegistryServer: "https://registry.npmmirror.com"

# Electron 镜像通过环境变量设置，Yarn Berry 不支持 .npmrc 中的 ELECTRON_MIRROR
# 在 .env 文件中设置（需要 dotenv 支持），或在 shell 中 export

Bun 的对应方案

Bun 也遵循 ELECTRON_MIRROR 环境变量：

ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ bun install

Bun 的 bunfig.toml 配置：

[install]
registry = "https://registry.npmmirror.com"
# 注意：截至 2024 年底，Bun 不直接在 bunfig.toml 支持 ELECTRON_MIRROR
# 需要通过环境变量设置

CI/CD 配置

GitHub Actions

# .github/workflows/build.yml
name: Build

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    
    env:
      # GitHub Actions 网络畅通，不需要镜像
      # 但可以通过 electron/cache 缓存加速
      ELECTRON_CACHE: ${{ github.workspace }}/.cache/electron
      
    steps:
      - uses: actions/checkout@v4
      
      # 缓存 Electron 二进制（大幅减少安装时间）
      - name: Cache Electron
        uses: actions/cache@v4
        with:
          path: ${{ env.ELECTRON_CACHE }}
          key: ${{ runner.os }}-electron-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-electron-
      
      - name: Install dependencies
        run: npm install
        env:
          ELECTRON_CACHE: ${{ env.ELECTRON_CACHE }}

自建 CI（国内服务器）

# 在国内 CI 环境中使用镜像
steps:
  - name: Setup npm mirror
    run: |
      npm config set registry https://registry.npmmirror.com
      npm config set ELECTRON_MIRROR https://npmmirror.com/mirrors/electron/
  
  - name: Install
    run: npm install

Jenkins / GitLab CI

// Jenkinsfile
stage('Install') {
    environment {
        ELECTRON_MIRROR = 'https://npmmirror.com/mirrors/electron/'
        NPM_CONFIG_REGISTRY = 'https://registry.npmmirror.com'
    }
    steps {
        sh 'npm install'
    }
}

# .gitlab-ci.yml
variables:
  ELECTRON_MIRROR: "https://npmmirror.com/mirrors/electron/"
  NPM_CONFIG_REGISTRY: "https://registry.npmmirror.com"

install:
  script:
    - npm install

验证方法

安装成功后验证 Electron 是否可用：

# 查看安装的 Electron 版本
npx electron --version
# 或
./node_modules/.bin/electron --version

# 验证二进制文件存在
ls node_modules/electron/dist/
# Linux: electron  (可执行文件)
# Windows: electron.exe
# macOS: Electron.app/

# 检查 path.txt（记录实际路径）
cat node_modules/electron/path.txt

如果 path.txt 存在且内容指向有效的可执行文件，说明安装成功。

2024-2025 最新可用镜像

经过实测，以下镜像在 2025 年仍可用（按稳定性排序）：

注意：各镜像的可用性随时间变化，如果某个镜像失效，请先尝试 npmmirror。

常见问题排查

# 查看 install.js 的详细日志
DEBUG=electron-download npm install electron

# 清除缓存重新安装
npm cache clean --force
rm -rf node_modules/electron
npm install electron

# 指定版本安装（有时最新版镜像同步有延迟）
npm install electron@31.0.0

# 网络诊断
curl -I https://npmmirror.com/mirrors/electron/
curl -I https://github.com/electron/electron/releases

掌握这些方法，Electron 的安装问题就再也不会困扰你了。