ARM Mac下Electron React Boilerplate集成node-pty失败求助

问题概述 #

基于 Electron React Boilerplate 搭建的项目，集成 node-pty 时出现两类错误：

• 开发环境启动（npm run start）时报错：TypeError: Cannot read properties of undefined (reading 'spawn')
• 构建后运行时报错，提示原生模块编译版本不匹配（NODE_MODULE_VERSION 116 vs 115），且找不到 pty.node 文件

复现步骤 #

git clone --depth 1 --branch main https://github.com/electron-react-boilerplate/electron-react-boilerplate.git test-electron-nodepty
cd test-electron-nodepty
npm i
cd release/app
npm i --save node-pty
cd ../..
npm i

修改 src/main/main.ts 加入测试代码：

import pty from 'node-pty';

pty.spawn('bash', [], {
  name: 'xterm-color',
  cols: 80,
  rows: 30,
  cwd: process.env.HOME,
  env: process.env,
});

错误原因 #

1. 开发环境错误：node-pty 作为原生模块，未针对 Electron 内置的 Node 版本编译，导致模块导入异常
2. 构建后错误：安装 node-pty 时使用系统 Node 版本编译，与 Electron 内置 Node 的 NODE_MODULE_VERSION 不匹配；ARM 架构 Mac 还可能存在编译目标架构不一致的问题

解决方案（ARM 架构 Mac 适配） #

1. 清理现有依赖残留 #

# 清理 release/app 下的 node-pty 残留
cd release/app
rm -rf node_modules/node-pty package-lock.json
# 清理根目录依赖和缓存
cd ../..
rm -rf node_modules package-lock.json
npm cache clean --force

2. 安装 electron-rebuild #

在项目根目录安装 electron-rebuild，用于将原生模块重新编译为适配当前 Electron 版本的版本：

npm install --save-dev electron-rebuild

3. 重新安装并编译 node-pty #

# 进入 release/app 安装 node-pty
cd release/app
npm install node-pty
# 回到根目录执行定向重新编译
cd ../..
npx electron-rebuild -f -w node-pty

参数说明：-f 强制重新编译，-w node-pty 指定仅处理 node-pty 模块，提升效率

4. 配置自动编译（可选） #

在项目根目录的 package.json 中添加 postinstall 脚本，确保每次安装依赖后自动编译原生模块：

"scripts": {
  "postinstall": "electron-rebuild"
}

5. 验证运行 #

• 启动开发环境：

npm run start

• 构建并验证生产版本：

npm run build
# 启动打包后的应用
open release/mac/test-electron-nodepty.app

6. ARM 架构特殊适配 #

如果上述步骤仍未解决，指定 ARM64 架构重新编译：

npx electron-rebuild -f -w node-pty --arch arm64

或安装时直接指定平台和架构：

cd release/app
npm install node-pty --target_platform=darwin --target_arch=arm64
cd ../..
npx electron-rebuild

内容的提问来源于stack exchange，提问作者Daniel Centore