原生代码与 Electron

Electron 最强大的功能之一，就是能够将 Web 技术与原生代码相结合 - 能在需要时用于计算密集型逻辑，亦或是少量的原生用户界面。

Electron 是通过在“原生 Node.js 插件”之上构建来实现的。你很有可能已经遇到了几个了 - 比如著名的 sqlite 就是使用原生代码将 JavaScript 与原生技术结合到了一起。你可以使用这个特性扩展你的 Electron 应用程序，使其能做到原生应用程序能完成的任何事：

访问 JavaScript 里不可用的原生平台 API。你可以使用 macOS、Windows、Linux 操作系统里的任意 API。
创建能与原生桌面框架交互的 UI 组件。
集成现有的原生库。
实现运行起来比 JavaScript 还快的需要高性能的代码。

原生 Node.js 插件是动态链接的共享对象（在类 Unix 系统上）或者 DLL 文件（在 Windows 上），可以使用 require() 或 import 函数加载到 Node.js 或 Electron 里。它们的行为就像是普通的 JavaScript 模块，但为用 C++，Rust，或其他可以编译成原生代码的语言编写的代码提供了一个接口。

教程：为 Electron 创建一个原生 Node.js 插件

本教程将带你构建一个能够在 Electron 应用程序内使用的基础 Node.js 原生插件。我们会聚焦于所有平台都共通的概念，使用 C++ 作为实现语言。一旦你完成了对所有原生 Node.js 插件都适用的本教程，你就可以移步到我们的平台限定教程的其中一个。

要求

本教程假定你已经安装了 Node.js 和 npm，以及在你的平台上编译代码所需的必要基础工具（比如 Windows 上的 Visual Studio，macOS 上的 Xcode，Linux 上的 GCC/Clang）。你可以在 node-gyp readme 里找到详细说明。

要求：macOS

要在 macOS 上构建原生 Node.js 插件，你需要安装 Xcode 命令行工具。其提供了必要的编译器和构建工具（即 clang、clang++ 以及 make）。下列命令会在你尚未安装命令行工具时指引你安装。

xcode-select --install

要求：Windows

官方的 Node.js 安装程序提供了安装“适用于原生模块的工具”的可选项，其会安装编译基础 C++ 模块所需的一切工具 - 具体来说是 Python 3 和 “Visual Studio 使用 C++ 的桌面开发” 工作负荷。又或者，你可以使用 chocolatey，winget，或 Windows 商店。

要求：Linux

受支持的 Python 版本
make
一个合适的 C/C++ 编译器工具链，比如 GCC。

1. 创建一个包

首先，创建一个将会包含你的原生插件的 Node.js 包：

mkdir my-native-addon
cd my-native-addon
npm init -y

这会创建一个基础的 package.json 文件。接下来，我们安装必要的依赖：

npm install node-addon-api bindings

node-addon-api：这是低级 Node.js API 的 C++ 包装层，使构建插件更加轻松。它提供了面向对象的 C++ API，比原始的 C 风格 API 更方便和安全。
bindings：一个能简化编译后的原生插件的加载过程的辅助模块。它负责自动寻找你编译后的 .node 文件。

现在，我们更新 package.json，加入适当的构建脚本。我们会在下文解释这些具体是做什么的。

package.json
{
  "name": "my-native-addon",
  "version": "1.0.0",
  "description": "A native addon for Electron",
  "main": "js/index.js",
  "scripts": {
    "clean": "node -e \"require('fs').rmSync('build', { recursive: true, force: true })\"",
    "build": "node-gyp configure && node-gyp build"
  },
  "dependencies": {
    "bindings": "^1.5.0",
    "node-addon-api": "^8.3.0"
  },
  "devDependencies": {
    "node-gyp": "^11.1.0"
  }
}

这些脚本将会：

clean：删除构建目录，以便进行全新构建
build：运行标准的 node-gyp 构建流程来编译你的插件

2. 搭建构建系统

Node.js 插件使用叫做 node-gyp 的构建系统，这是一个用 Node.js 编写的跨平台命令行工具。它在后台使用平台特定的构建工具编译 Node.js 的原生插件模块：

在 Windows 上：Visual Studio
在 macOS 上：Xcode 或命令行工具
在 Linux 上：GCC 或类似的编译器

配置 `node-gyp`

binding.gyp 文件是一个类 JSON 的配置文件，告诉 node-gyp 如何构建你的原生插件。它类似于 makefile 或工程文件，但采用的是独立于平台的格式。我们创建一个基础的 binding.gyp 文件：

binding.gyp
{
  "targets": [
    {
      "target_name": "my_addon",
      "sources": [
        "src/my_addon.cc",
        "src/cpp_code.cc"
      ],
      "include_dirs": [
        "<!@(node -p \"require('node-addon-api').include\")",
        "include"
      ],
      "dependencies": [
        "<!(node -p \"require('node-addon-api').gyp\")"
      ],
      "defines": [
        "NODE_ADDON_API_CPP_EXCEPTIONS"
      ],
      "cflags!": ["-fno-exceptions"],
      "cflags_cc!": ["-fno-exceptions"],
      "xcode_settings": {
        "GCC_ENABLE_CPP_EXCEPTIONS": "YES",
        "CLANG_CXX_LIBRARY": "libc++",
        "MACOSX_DEPLOYMENT_TARGET": "10.14"
      },
      "msvs_settings": {
        "VCCLCompilerTool": {
          "ExceptionHandling": 1
        }
      }
    }
  ]
}

我们分解一下这个配置：

target_name：你的插件名。这决定了编译后的模块的文件名（my_addon.node）。
sources：要编译的源文件列表。我们有两个文件：主插件文件和实际的 C++ 实现。
include_dirs：头文件的搜索目录。看起来晦涩的代码行 <!@(node -p \"require('node-addon-api').include\") 的作用是运行一个 Node.js 命令来获取 node-addon-api 包含目录的路径。
dependencies：node-addon-api 依赖。和包含目录类似，这行也执行了一个 Node.js 命令来获取合适的配置。
defines：预处理器宏定义。这里我们为 node-addon-api 启用了 C++ 异常。平台特定设置：
cflags! 和 cflags_cc!：适用于类 Unix 系统的编译器标志
xcode_settings：macOS/Xcode 编译器特有的设置
msvs_settings：Windows 上 Microsoft Visual Studio 特有的设置

现在，为我们的项目创建目录结构：

mkdir src
mkdir include
mkdir js

这将会创建：

src/：源文件会放在这里
include/：放置头文件
js/：放置 JavaScript 包装层

3. 来自 C++ 的“Hello World”

先从在头文件里定义我们的 C++ 接口起步。创建 include/cpp_code.h：

#pragma once
#include <string>

namespace cpp_code {
    // 一个简单的函数，接受一个字符串输入并返回一个字符串
    std::string hello_world(const std::string& input);
} // cpp_code 命名空间

#pragma once 指令是一个头文件防护指令，能够避免文件在相同的编译单元内被多次包含。实际的函数声明放在一个命名空间里面，以避免潜在的命名冲突。

接下来，我们在 src/cpp_code.cc 里实现这个函数：

src/cpp_code.cc
#include <string>
#include "../include/cpp_code.h"

namespace cpp_code {
    std::string hello_world(const std::string& input) {
        // 简单拼接字符串然后返回
        return "Hello from C++! You said: " + input;
    }
} // cpp_code 命名空间

这是个简单的实现，只是向输入字符串添加一些文本然后返回它。

现在，让我们编写将 C++ 代码与 Node.js/JavaScript 世界连接起来的插件代码。创建 src/my_addon.cc：

src/my_addon.cc
#include <napi.h>
#include <string>
#include "../include/cpp_code.h"

// 创建一个将会暴露给 JavaScript 的类
class MyAddon : public Napi::ObjectWrap<MyAddon> {
public:
    // 这个静态方法定义了 JavaScript 的类
    static Napi::Object Init(Napi::Env env, Napi::Object exports) {
        // 定义带有方法的 JavaScript 类
        Napi::Function func = DefineClass(env, "MyAddon", {
            InstanceMethod("helloWorld", &MyAddon::HelloWorld)
        });

        // 创建构造函数的持久引用
        Napi::FunctionReference* constructor = new Napi::FunctionReference();
        *constructor = Napi::Persistent(func);
        env.SetInstanceData(constructor);

        // 在 exports 对象上设置构造函数
        exports.Set("MyAddon", func);
        return exports;
    }

    // 构造函数
    MyAddon(const Napi::CallbackInfo& info)
        : Napi::ObjectWrap<MyAddon>(info) {}

private:
    // 将会暴露给 JavaScript 的方法
    Napi::Value HelloWorld(const Napi::CallbackInfo& info) {
        Napi::Env env = info.Env();

        // 验证参数（只需要一个字符串）
        if (info.Length() < 1 || !info[0].IsString()) {
            Napi::TypeError::New(env, "Expected string argument").ThrowAsJavaScriptException();
            return env.Null();
        }

        // 将 JavaScript 字符串转换为 C++ 字符串
        std::string input = info[0].As<Napi::String>();

        // 调用我们的 C++ 函数
        std::string result = cpp_code::hello_world(input);

        // 将 C++ 字符串转换回 JavaScript 字符串并返回
        return Napi::String::New(env, result);
    }
};

// 初始化插件
Napi::Object Init(Napi::Env env, Napi::Object exports) {
    return MyAddon::Init(env, exports);
}

// 注册初始化函数
NODE_API_MODULE(my_addon, Init)

我们分解一下这个代码：

我们定义了一个继承自 Napi::ObjectWrap<MyAddon> 的 MyAddon 类，它负责为 JavaScript 包装我们的 C++ 类。
Init 静态方法：2.1 定义了一个带有叫做 helloWorld 的方法的 JavaScript 类2.2 为构造函数创建了一个持久引用（为了避免受到垃圾回收影响）2.3 导出类的构造函数
该构造函数只是将其参数传递给了父类。
HelloWorld 方法： 4.1 获取 Napi 环境4.2 验证参数（只需要一个字符串）4.3 将 JavaScript 字符串转换为 C++ 字符串4.4 调用我们的 C++ 函数4.5 将 C++ 字符串转换回 JavaScript 字符串并返回它
我们定义了一个初始化函数并使用 NODE_API_MODULE 宏注册它，这会让我们的模块能够被 Node.js 加载.

现在，我们创建一个 JavaScript 包装层，让插件更容易使用。创建 js/index.js：

js/index.js
const EventEmitter = require('node:events')

// 使用“bindings”模块加载原生插件
// 它会在各种地方寻找编译后的 .node 文件
const bindings = require('bindings')
const native = bindings('my_addon')

// 创建一个不错的 JavaScript 包装层
class MyNativeAddon extends EventEmitter {
  constructor () {
    super()

    // 创建我们 C++ 类的一个实例
    this.addon = new native.MyAddon()
  }

  // 用更友好的 JavaScript API 包装 C++ 方法
  helloWorld (input = '') {
    if (typeof input !== 'string') {
      throw new TypeError('Input must be a string')
    }
    return this.addon.helloWorld(input)
  }
}

// 导出单个实例
if (process.platform === 'win32' || process.platform === 'darwin' || process.platform === 'linux') {
  module.exports = new MyNativeAddon()
} else {
  // 为不支持的平台提供后备方案
  console.warn('Native addon not supported on this platform')

  module.exports = {
    helloWorld: (input) => `Hello from JS! You said: ${input}`
  }
}

这个 JavaScript 包装层：

使用 bindings 加载我们已编译的原生插件
创建一个继承自 EventEmitter 的类（适用于未来可能需要触发事件的扩展功能）
实例化我们的 C++ 类并提供一个更简单的 API
在 JavaScript 侧添加一些输入验证
导出我们包装层的单个实例
优雅地处理平台不受支持的情况

构建并测试插件

现在我们可以构建我们的原生插件：

npm run build

这会运行 node-gyp configure 和 node-gyp build 将我们的 C++ 代码编译为一个 .node 文件。让我们创建一个简单的测试脚本来验证一切是否正常工作。在项目根目录创建 test.js：

test.js
// 加载我们的插件
const myAddon = require('./js')

// 尝试调用 helloWorld 函数
const result = myAddon.helloWorld('This is a test')

// 应当会输出：“Hello from C++! You said: This is a test”
console.log(result)

运行测试：

node test.js

如果一切正常，你应该会看到：

Hello from C++! You said: This is a test

在 Electron 里使用插件

要在一个 Electron 应用程序里使用这个插件，你需要：

将其作为依赖项包含在你的 Electron 项目中
针对你特定的 Electron 版本构建它。 electron-forge 自动为你处理这一步 - 要获取更多详情，请参阅 Node 原生模块。
在一个启用了 Node.js 的进程里像其他模块一样导入并使用它。

// 在你的主进程内
const myAddon = require('my-native-addon')

console.log(myAddon.helloWorld('Electron'))

参考资料和延伸阅读

原生插件开发可以使用 C++ 以外的几种语言编写。 Rust 可以使用像 napi-rs，neon，或 node-bindgen 之类的 Crate 来开发。在 macOS 上可以通过 Objective-C++ 使用 Objective-C/Swift。

具体的实现细节因平台差异而有很大的不同，尤其是访问平台特定的 API 或者 UI 框架的时候，比如 Windows 的 Win32 API、COM 组件、UWP/WinRT - 或者 macOS 的 Cocoa、AppKit、ObjectiveC 运行时。

这就意味着你编写原生代码时很可能需要两组参考资料：首先，在 Node.js 侧，使用 N-API 文档来学习如何创建并向 JavaScript 暴露复杂的结构体 - 比如异步线程安全函数的调用或者创建 JavaScript 原生对象（error、promise 等）。其次，在你所使用的技术侧，你很可能需要查阅它们的底层文档：

教程：为 Electron 创建一个原生 Node.js 插件

要求​

要求：macOS​

要求：Windows​

要求：Linux​

1. 创建一个包​

2. 搭建构建系统​

配置 node-gyp​

3. 来自 C++ 的“Hello World”​

构建并测试插件​

在 Electron 里使用插件​

参考资料和延伸阅读​

要求