使用国内镜像源解决 Electron 安装卡在 postinstall 的问题

在国内开发 Electron 应用时，经常会遇到以下情况：

npm info run electron@38.0.0 postinstall node_modules/electron node install.js

安装长时间卡住，尤其在国内网络环境下。这是因为 Electron 默认从 GitHub 下载二进制文件，而国内访问 GitHub 下载速度慢甚至失败。本文将介绍如何使用 国内镜像源，在 Windows、macOS 和 Linux 上快速安装 Electron。

一、问题分析

1. Electron 安装流程

   当执行：

   npm install electron@38.0.0
   

   npm 会执行 postinstall 脚本：

   node_modules/electron/install.js
   

   它会下载对应平台的二进制文件（.app、.exe、.AppImage 等），用于运行 Electron。

2. 卡住原因

   • GitHub 下载速度慢或被限速。
   • VPN 或代理配置不当。
   • 国内防火墙对大文件下载有限制。

二、解决方案：使用国内镜像源

Electron 提供了环境变量 ELECTRON_MIRROR，用于指定二进制文件的下载源。

1️⃣ 临时设置镜像源

macOS / Linux：

export ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"
npm install electron@38.0.0

Windows（PowerShell）：

setx ELECTRON_MIRROR "https://npmmirror.com/mirrors/electron/"
npm install electron@38.0.0

• 说明：临时设置只在当前终端有效。关闭终端后失效。

2️⃣ 永久设置镜像源

macOS / Linux（以 zsh 为例）：

1. 打开配置文件：

nano ~/.zshrc

2. 添加：

export ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"

3. 保存退出并生效：

source ~/.zshrc

Windows（PowerShell 永久环境变量）：

1. 打开 PowerShell（管理员模式）：

[Environment]::SetEnvironmentVariable("ELECTRON_MIRROR", "https://npmmirror.com/mirrors/electron/", "User")

2. 重启 PowerShell，使环境变量生效。

3️⃣ 安装 Electron

设置好镜像后，执行：

npm install electron@38.0.0

• macOS M1/M2：确保下载 ARM64 架构版本。
• Linux：通常下载 .AppImage 或 .tar.gz 文件。
• Windows：下载 .exe 或 .zip 文件。

下载完成后，二进制文件会位于：

node_modules/electron/dist/

三、验证安装是否成功

1. 查看 Electron 版本：

npx electron --version

输出版本号如 v38.0.0 表示安装成功。

2. 检查二进制文件：

• macOS：

ls node_modules/electron/dist/Electron.app

• Windows：

dir node_modules\electron\dist\electron.exe

• Linux：

ls node_modules/electron/dist/electron

3. 运行 Electron：

# macOS
./node_modules/electron/dist/Electron.app/Contents/MacOS/Electron .
# Windows
.\node_modules\electron\dist\electron.exe .
# Linux
./node_modules/electron/dist/electron .

四、常见注意事项

1. 架构匹配

   • macOS M1/M2 → ARM64
   • Intel 芯片 → x64
   • Linux 和 Windows → x64

2. npm 版本

   • 建议使用最新稳定版 npm。旧版本可能无法识别镜像环境变量。

3. 清理缓存

   • 如安装仍卡住，可执行：

npm cache clean --force

4. 全局 vs 项目本地

   • 推荐项目本地安装：

npm install electron@38.0.0 --save-dev

• 全局安装仅用于命令行测试。

五、总结

通过使用国内镜像源，可以在 Windows、macOS 和 Linux 上解决 Electron 安装卡在 postinstall 的问题，稳定、高速下载二进制文件。

• 临时设置：export / setx
• 永久设置：配置 shell 或系统环境变量
• 安装命令：npm install electron

这样，无论是跨平台开发还是团队协作，都能快速搭建 Electron 环境，避免网络问题导致的安装失败。