Electron Forge+Webpack渲染进程中serialport绑定加载失败问题

核心问题分析 #

serialport是Node.js原生模块，无法被Webpack直接打包，且需要与当前Electron版本的ABI（应用二进制接口）完全匹配，这是导致导入错误和原生构建缺失的主要原因。以下是分步解决方法：

1. 配置Webpack排除serialport打包 #

修改项目根目录下的webpack.renderer.config.js，将serialport添加到externals中，避免Webpack尝试打包该原生模块：

module.exports = {
  // 保留原有配置...
  externals: {
    serialport: 'commonjs serialport'
  }
};

2. 通过Preload脚本安全暴露serialport API #

不要在渲染进程直接导入serialport，而是通过Preload脚本封装所需功能，再通过contextBridge暴露给渲染进程：

preload.js 代码：

const { contextBridge } = require('electron');
const { SerialPort } = require('serialport');

// 封装需要的串口操作方法
contextBridge.exposeInMainWorld('serialPortAPI', {
  // 获取串口列表
  listPorts: async () => SerialPort.list(),
  // 可添加其他方法，比如打开串口、读写数据等
  openPort: (path, options) => new SerialPort({ path, ...options }),
  // 示例：监听串口数据
  onData: (port, callback) => port.on('data', callback)
});

在主进程（main.js）中配置Preload：

确保主窗口的webPreferences正确指定preload路径，保持contextIsolation开启（即使是内部工具，这也是更安全的做法）：

const { BrowserWindow, app } = require('electron');
const path = require('path');

function createWindow() {
  const mainWindow = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
      contextIsolation: true // 默认开启，无需修改
    }
  });

  mainWindow.loadURL('http://localhost:3000');
}

app.whenReady().then(createWindow);

3. 正确重建serialport原生模块 #

不要使用独立的electron-rebuild命令，改用Electron Forge内置的重建工具，它会自动匹配当前Electron的环境参数（ABI、平台等）：

npm run rebuild -- --force --module-name=serialport

或者在package.json的scripts中添加快捷命令：

"scripts": {
  // 保留原有脚本...
  "rebuild-serialport": "electron-forge rebuild --force --module-name=serialport"
}

执行npm run rebuild-serialport即可完成重建。

4. 确保serialport版本与Electron兼容 #

如果重建后仍提示ABI不匹配，检查serialport版本是否支持当前Electron的ABI。例如Electron 22对应的ABI是110，可安装兼容版本：

npm install serialport@10.5.0

安装完成后再次执行重建命令。

5. 渲染进程中使用暴露的API #

在renderer.js中直接调用全局暴露的serialPortAPI：

async function loadSerialPorts() {
  try {
    const ports = await window.serialPortAPI.listPorts();
    console.log('可用串口:', ports);
  } catch (err) {
    console.error('获取串口列表失败:', err);
  }
}

// 页面加载后执行
document.addEventListener('DOMContentLoaded', loadSerialPorts);

内容的提问来源于stack exchange，提问作者Joe Jankowiak