Next.js 14+Electron环境下.node插件加载失败（MODULE_NOT_FOUND）求助

1. 先验证Addon文件本身的有效性 #

• 直接用Node.js测试加载：在addon.node所在目录打开终端，执行node -e "require('./addon.node')"。如果这里报错，说明Addon本身有问题，而非项目配置：
  • 重新编译Addon：用electron-rebuild匹配Electron的Node版本，命令：npx electron-rebuild -f -w [你的Addon名称]
  • 检查编译日志：查看编译过程中是否有错误（比如依赖缺失、Node版本不匹配），Electron的Node版本可通过electron -v查询，再对应官方Node版本对照表，确保编译时使用的node-gyp或electron-rebuild针对该版本
  • 校验文件完整性：对比重新编译后的addon.node文件大小，若多次编译大小差异大，可能是编译环境问题或文件损坏

2. 排查Next.js的路径与打包配置问题 #

• 绝对路径加载：Next.js的模块解析逻辑与普通Node.js不同，即使同目录，相对路径可能失效。改用__dirname拼接绝对路径：

  import path from 'path';
  const addon = require(path.join(__dirname, './addon.node'));
  

  同时打印console.log(__dirname)确认代码实际运行的路径，检查addon.node是否存在于该路径下
• 配置Next.js的外部依赖：在next.config.mjs中添加serverComponentsExternalPackages，让Next.js不打包Addon，直接由Node.js加载：

  /** @type {import('next').NextConfig} */
  const nextConfig = {
    serverComponentsExternalPackages: ['your-addon-name'], // 若Addon是单独包填包名，直接用文件可填所在目录
    webpack: (config, { isServer }) => {
      if (isServer) {
        // 配置webpack处理.node文件
        config.module.rules.push({
          test: /\.node$/,
          use: 'file-loader',
        });
      }
      return config;
    },
  };
  export default nextConfig;
  

  记得安装file-loader：npm install file-loader --save-dev

3. 处理Electron进程隔离问题 #

• 禁止在渲染进程直接加载Addon：Next.js的Client Component运行在Electron的渲染进程（浏览器环境），默认沙箱隔离无法访问Node.js模块。必须将Addon加载放在主进程，通过IPC通信调用：
  • 主进程代码（main.js）：

    const { ipcMain } = require('electron');
    const addon = require('./path/to/addon.node');
    // 注册IPC handler
    ipcMain.handle('invoke-addon-method', (_, args) => {
      return addon.yourMethod(args);
    });
    

  • 客户端组件/页面调用：

    // 需通过preload脚本暴露ipcRenderer，或配置BrowserWindow的nodeIntegration（不推荐）
    const { ipcRenderer } = window.require('electron');
    const result = await ipcRenderer.invoke('invoke-addon-method', [yourArgs]);
    

  • 安全配置：推荐用preload脚本暴露IPC接口，避免开启nodeIntegration: true（不安全）。preload.js示例：

    const { ipcRenderer, contextBridge } = require('electron');
    contextBridge.exposeInMainWorld('electronAPI', {
      callAddon: (args) => ipcRenderer.invoke('invoke-addon-method', args),
    });
    

    然后在Client Component中通过window.electronAPI.callAddon(args)调用

4. 检查文件权限与大小写 #

• Linux/macOS下赋予执行权限：chmod +x addon.node
• Windows下检查是否被杀毒软件拦截，或文件是否被锁定
• 确保代码中的文件名与实际文件大小写一致（Linux/macOS区分大小写，Windows不区分，但跨平台需统一）

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