解决 pnpm 安装 Electron 缺少二进制文件的问题
问题描述
使用 pnpm 安装 Electron 时，可能出现以下错误：
Error: Electron failed to install correctly, please delete node_modules/electron and try installing again
或者在运行时出现类似错误：
Cannot find module '../build/Release/electron'
The module '../build/Release/electron.node' was compiled against a different Node.js version
原因分析
Electron 是包含平台特定二进制文件的包，它需要在安装时下载对应操作系统的可执行文件。
pnpm 的问题：
- pnpm 使用硬链接和符号链接组织
node_modules - 对 Electron 的二进制下载和安装处理与 npm/yarn 不同
- 某些情况下，Electron 的 postinstall 脚本无法正确执行，导致二进制文件下载失败或不完整
解决方案
解决方案 1：使用 npm 安装（推荐用于 Electron 项目）
优点：完全兼容，无需额外配置
缺点：需要使用 npm 作为包管理器
步骤 1：清理现有安装
# PowerShell 5.1 兼容命令
cd gui
Remove-Item -Recurse -Force node_modules
Remove-Item -Force package-lock.json
Remove-Item -Force pnpm-lock.yaml
步骤 2：使用 npm 安装
npm install
步骤 3：安装 Electron 二进制文件
# 重新安装 Electron 以确保二进制文件正确下载
npm rebuild electron
步骤 4：验证安装
# 检查 Electron 是否正确安装
npm run dev
解决方案 2：配置 pnpm 安装 Electron 的选项（保持使用 pnpm）
优点：可以使用 pnpm 的速度优势
缺点：需要手动配置
步骤 1：修改 package.json
在 package.json 中添加 pnpm 配置：
{"name": "animation-builder-gui","version": "0.1.0","scripts": {"dev": "node scripts/start.js","build": "vite build && electron-builder"},"pnpm": {"peerDependencyRules": {"ignoreMissing": []},"onlyBuiltDependencies": ["electron"]},"devDependencies": {"electron": "^28.3.3","electron-builder": "^24.9.1"}
}
配置说明
onlyBuiltDependencies: 指定只构建 electron 的依赖，不执行其他依赖的构建脚本，避免不必要的构建peerDependencyRules: 配置对等依赖的规则，确保依赖关系正确解析
步骤 2：设置环境变量
创建或修改 .npmrc 文件（在项目根目录或 gui 目录）：
# .npmrc
shamefully-hoist=true
strict-peer-dependencies=false
或者使用 PowerShell 设置环境变量：
# PowerShell 5.1 兼容 - 设置 shamefully-hoist
$env:PNPM_SHAMELEXY_HOIST = "true"
pnpm install
步骤 3：重新安装
# 清理现有安装
Remove-Item -Recurse -Force node_modules
Remove-Item -Force pnpm-lock.yaml# 使用 pnpm 安装
pnpm install# 强制重新安装 Electron
pnpm rebuild electron
步骤 4：验证安装
# 检查 electron 二进制文件是否存在
Test-Path node_modules\electron\dist\electron.exe# 如果返回 False，手动下载二进制文件
node_modules\.bin\electron install
两种方案的详细对比
使用 npm（方案1）
适用场景：
- 初次搭建项目
- 遇到频繁的 pnpm 相关错误
- 团队中大部分人使用 npm
操作步骤：
# 1. 切换目录
cd gui# 2. 删除锁定文件
Remove-Item -Recurse -Force node_modules
Remove-Item -Force pnpm-lock.yaml, package-lock.json -ErrorAction SilentlyContinue# 3. 使用 npm 安装
npm install# 4. 验证
npm run dev
配置 pnpm（方案2）
适用场景：
- 希望充分利用 pnpm 的磁盘空间节省
- 项目已经有 pnpm 工作流
- 团队统一使用 pnpm
操作步骤：
# 1. 修改 package.json 添加 pnpm 配置
# （需要编辑文件添加配置）# 2. 创建 .npmrc 文件
echo "shamefully-hoist=true" | Out-File -Encoding utf8 .npmrc# 3. 重新安装
Remove-Item -Recurse -Force node_modules
Remove-Item -Force pnpm-lock.yaml
pnpm install# 4. 强制安装 Electron 二进制
pnpm exec electron install# 5. 验证
pnpm run dev
故障排查
问题 1：安装后仍然报错
尝试以下步骤：
# PowerShell 5.1 兼容
cd gui# 完全清理
Remove-Item -Recurse -Force node_modules
Remove-Item -Recurse -Force $(Get-ChildItem -Filter "pnpm-lock.yaml" -ErrorAction SilentlyContinue | Select-Object -ExpandProperty FullName) -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force $(Get-ChildItem -Filter "package-lock.json" -ErrorAction SilentlyContinue | Select-Object -ExpandProperty FullName) -ErrorAction SilentlyContinue# 清除缓存
npm cache clean --force
# 如果是 pnpm
pnpm store prune# 重新安装
npm install
# 或
pnpm install
问题 2：代理或网络问题
如果下载 Electron 二进制文件失败：
# 设置国内镜像（PowerShell 5.1）
$env:ELECTRON_MIRROR = "https://npmmirror.com/mirrors/electron/"
npm install# 或使用 pnpm
$env:ELECTRON_MIRROR = "https://npmmirror.com/mirrors/electron/"
pnpm install
问题 3：权限问题
# 以管理员身份运行 PowerShell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
总结
- 使用 npm：简单直接，适合快速启动
- 配置 pnpm：适合长期使用 pnpm 的项目，需额外配置