解决 pnpm 安装 Electron 缺少二进制文件的问题

解决 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 的项目，需额外配置