C++ 插件

插件是用 C++ 编写的动态链接共享对象。 require() 函数可以将插件加载为普通的 Node.js 模块。 插件提供了 JavaScript 和 C/C++ 库之间的接口。

实现插件有三个选项:Node-API、nan,或直接使用内部 V8、libuv 和 Node.js 库。 除非需要直接访问 Node-API 未暴露的功能,否则请使用 Node-API。 有关 Node-API 的更多信息,请参阅使用 Node-API 的 C/C++ 插件

不使用 Node-API 时,实现插件很复杂,涉及若干组件和 API 的知识:

  • V8: Node.js 用来提供 JavaScript 实现的 C++ 库。 V8 提供了创建对象、调用函数等的机制。 V8 的 API 主要记录在 v8.h 头文件(Node.js 源代码树中的 deps/v8/include/v8.h)中,该文件也可在线获取。

  • libuv: 实现 Node.js 事件循环、其工作线程和平台所有异步行为的 C 库。 它还充当跨平台抽象库,在所有主要的操作系统上都可以轻松、类似于 POSIX 的访问,例如与文件系统、套接字、定时器、以及系统事件进行交互。 libuv 还提供类似于 POSIX 线程的线程抽象,用于需要超越标准事件循环的更复杂的异步插件。 插件作者应该避免使用 I/O 或其他时间密集型任务阻塞事件循环,通过将工作通过 libuv 分流到非阻塞系统操作、工作线程、或 libuv 线程的自定义使用来实现。

  • 内部 Node.js 库。 Node.js 自身导出了插件可以使用的 C++ API,其中最重要的是 node::ObjectWrap 类。

  • Node.js 包括了其他静态链接库,包括 OpenSSL。 这些其他库位于 Node.js 源代码树的 deps/ 目录中。 只有 libuv、OpenSSL、V8 和 zlib 符号被 Node.js 有目的地重新导出,并且可以被插件在不同程度上使用。 有关其他信息,请参阅链接到 Node.js 中包含的库


Addons are dynamically-linked shared objects written in C++. The require() function can load addons as ordinary Node.js modules. Addons provide an interface between JavaScript and C/C++ libraries.

There are three options for implementing addons: Node-API, nan, or direct use of internal V8, libuv, and Node.js libraries. Unless there is a need for direct access to functionality which is not exposed by Node-API, use Node-API. Refer to C/C++ addons with Node-API for more information on Node-API.

When not using Node-API, implementing addons is complicated, involving knowledge of several components and APIs:

  • V8: the C++ library Node.js uses to provide the JavaScript implementation. V8 provides the mechanisms for creating objects, calling functions, etc. V8's API is documented mostly in the v8.h header file (deps/v8/include/v8.h in the Node.js source tree), which is also available online.

  • libuv: The C library that implements the Node.js event loop, its worker threads and all of the asynchronous behaviors of the platform. It also serves as a cross-platform abstraction library, giving easy, POSIX-like access across all major operating systems to many common system tasks, such as interacting with the file system, sockets, timers, and system events. libuv also provides a threading abstraction similar to POSIX threads for more sophisticated asynchronous addons that need to move beyond the standard event loop. Addon authors should avoid blocking the event loop with I/O or other time-intensive tasks by offloading work via libuv to non-blocking system operations, worker threads, or a custom use of libuv threads.

  • Internal Node.js libraries. Node.js itself exports C++ APIs that addons can use, the most important of which is the node::ObjectWrap class.

  • Node.js includes other statically linked libraries including OpenSSL. These other libraries are located in the deps/ directory in the Node.js source tree. Only the libuv, OpenSSL, V8, and zlib symbols are purposefully re-exported by Node.js and may be used to various extents by addons. See Linking to libraries included with Node.js for additional information.

All of the following examples are available for download and may be used as the starting-point for an addon.