name: electron-native-addon-builder description: 为Electron构建和打包原生Node.js插件，确保正确的ABI兼容性、支持交叉编译和自动重建 allowed-tools: Read, Write, Edit, Bash, Glob, Grep tags: [electron, native-modules, node-addon, n-api, build]

electron-native-addon-builder

为Electron构建和打包原生Node.js插件，确保正确的ABI（应用程序二进制接口）兼容性。此技能处理原生模块编译的复杂性、跨平台构建以及确保模块与Electron的Node.js版本正确配合。

能力

配置electron-rebuild用于原生模块编译
使用Electron头文件设置node-gyp
处理跨平台编译（Windows、macOS、Linux）
管理Electron和原生模块之间的ABI兼容性
为二进制分发配置prebuild/prebuild-install
为版本无关构建设置N-API模块
处理特定架构构建（x64、arm64、ia32）
与electron-builder集成进行打包

输入模式

{
  "type": "object",
  "properties": {
    "projectPath": {
      "type": "string",
      "description": "Electron项目根目录路径"
    },
    "nativeModules": {
      "type": "array",
      "description": "要处理的原生模块列表",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "version": { "type": "string" },
          "source": { "enum": ["npm", "local", "github"] }
        }
      }
    },
    "electronVersion": {
      "type": "string",
      "description": "目标Electron版本"
    },
    "targetPlatforms": {
      "type": "array",
      "items": { "enum": ["win32", "darwin", "linux"] }
    },
    "targetArchitectures": {
      "type": "array",
      "items": { "enum": ["x64", "arm64", "ia32"] }
    },
    "useNAPI": {
      "type": "boolean",
      "description": "使用N-API进行版本无关构建",
      "default": true
    },
    "prebuildConfig": {
      "type": "boolean",
      "description": "生成prebuild配置",
      "default": false
    }
  },
  "required": ["projectPath"]
}

输出模式

{
  "type": "object",
  "properties": {
    "success": { "type": "boolean" },
    "configuration": {
      "type": "object",
      "properties": {
        "electronRebuild": { "type": "object" },
        "nodeGyp": { "type": "object" },
        "packageJson": { "type": "object" }
      }
    },
    "scripts": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "command": { "type": "string" }
        }
      }
    },
    "warnings": { "type": "array", "items": { "type": "string" } }
  },
  "required": ["success"]
}

配置方法

electron-rebuild（推荐）

// package.json
{
  "scripts": {
    "postinstall": "electron-rebuild",
    "rebuild": "electron-rebuild -f -w native-module-name"
  },
  "devDependencies": {
    "@electron/rebuild": "^3.6.0"
  }
}

使用Electron头文件的node-gyp

# 为node-gyp设置Electron头文件
export npm_config_target=28.0.0
export npm_config_arch=x64
export npm_config_target_arch=x64
export npm_config_disturl=https://electronjs.org/headers
export npm_config_runtime=electron
export npm_config_build_from_source=true

npm install native-module

electron-builder集成

# electron-builder.yml
npmRebuild: true
buildDependenciesFromSource: true
nodeGypRebuild: false

asarUnpack:
  - "**/*.node"
  - "**/node_modules/native-module/**"

N-API配置

N-API提供跨Node.js版本的ABI稳定性：

// N-API模块的binding.gyp
{
  "targets": [
    {
      "target_name": "native_module",
      "sources": ["src/native_module.cc"],
      "include_dirs": [
        "<!@(node -p \"require('node-addon-api').include\")"
      ],
      "dependencies": [
        "<!(node -p \"require('node-addon-api').gyp\")"
      ],
      "defines": ["NAPI_VERSION=8", "NAPI_DISABLE_CPP_EXCEPTIONS"]
    }
  ]
}

Prebuild配置

用于分发预构建二进制文件：

// package.json
{
  "scripts": {
    "prebuild": "prebuild -t 28.0.0 -r electron -a x64 -a arm64",
    "prebuild-upload": "prebuild --upload-all $GITHUB_TOKEN"
  },
  "devDependencies": {
    "prebuild": "^12.1.0",
    "prebuild-install": "^7.1.1"
  }
}

交叉编译

从macOS/Linux编译Windows版本

# 使用electron-rebuild和wine
npx @electron/rebuild --platform=win32 --arch=x64

# 或使用prebuild
prebuild -t 28.0.0 -r electron --platform=win32 --arch=x64

从x64编译macOS ARM64版本

# 需要Xcode和arm64工具链
npx @electron/rebuild --arch=arm64

从macOS/Windows编译Linux版本

# 使用Docker
docker run -v $(pwd):/project electron-builder-linux \
  npx @electron/rebuild --platform=linux --arch=x64

常见原生模块

模块	使用场景	N-API支持
better-sqlite3	SQLite数据库	是
sharp	图像处理	是
node-pty	终端模拟	是
serialport	串口通信	是
robotjs	桌面自动化	有限
node-hid	USB HID设备	是

故障排除

ABI不匹配错误

Error: 模块是针对不同的Node.js版本编译的

解决方案：使用正确的Electron版本重新构建：

npx @electron/rebuild -v 28.0.0

缺少构建工具

Windows：安装Visual Studio Build Tools

npm install -g windows-build-tools

macOS：安装Xcode Command Line Tools

xcode-select --install

Linux：安装build-essential

sudo apt-get install build-essential

Python版本问题

# 为node-gyp指定Python版本
npm config set python /usr/bin/python3

最佳实践

尽可能使用N-API：提供版本无关的二进制文件
预构建二进制文件：避免在用户机器上编译
测试所有平台：原生模块在不同操作系统上行为不同
固定Electron版本：确保ABI兼容性
从ASAR中排除：原生模块必须解包
使用electron-rebuild：自动处理头文件

Electron原生插件构建器Skill electron-native-addon-builder