- assert 断言
- async_hooks 异步钩子
- async_hooks/context 异步上下文
- buffer 缓冲区
- C++插件
- C/C++插件(使用 Node-API)
- C++嵌入器
- child_process 子进程
- cluster 集群
- CLI 命令行
- console 控制台
- Corepack 核心包
- crypto 加密
- crypto/webcrypto 网络加密
- debugger 调试器
- deprecation 弃用
- dgram 数据报
- diagnostics_channel 诊断通道
- dns 域名服务器
- domain 域
- Error 错误
- events 事件触发器
- fs 文件系统
- global 全局变量
- http 超文本传输协议
- http2 超文本传输协议 2.0
- https 安全超文本传输协议
- inspector 检查器
- Intl 国际化
- module 模块
- module/cjs CommonJS 模块
- module/esm ECMAScript 模块
- module/package 包模块
- net 网络
- os 操作系统
- path 路径
- perf_hooks 性能钩子
- permission 权限
- process 进程
- punycode 域名代码
- querystring 查询字符串
- readline 逐行读取
- repl 交互式解释器
- report 诊断报告
- stream 流
- stream/web 网络流
- string_decoder 字符串解码器
- test 测试
- timers 定时器
- tls 安全传输层
- trace_events 跟踪事件
- tty 终端
- url 网址
- util 实用工具
- v8 引擎
- vm 虚拟机
- wasi 网络汇编系统接口
- worker_threads 工作线程
- zlib 压缩
Node.js v16.20.0 文档
- Node.js v16.20.0
- 目录
-
导航
- assert 断言
- async_hooks 异步钩子
- async_hooks/context 异步上下文
- buffer 缓冲区
- C++插件
- C/C++插件(使用 Node-API)
- C++嵌入器
- child_process 子进程
- cluster 集群
- CLI 命令行
- console 控制台
- Corepack 核心包
- crypto 加密
- crypto/webcrypto 网络加密
- debugger 调试器
- deprecation 弃用
- dgram 数据报
- diagnostics_channel 诊断通道
- dns 域名服务器
- domain 域
- Error 错误
- events 事件触发器
- fs 文件系统
- global 全局变量
- http 超文本传输协议
- http2 超文本传输协议 2.0
- https 安全超文本传输协议
- inspector 检查器
- Intl 国际化
- module 模块
- module/cjs CommonJS 模块
- module/esm ECMAScript 模块
- module/package 包模块
- net 网络
- os 操作系统
- path 路径
- perf_hooks 性能钩子
- permission 权限
- process 进程
- punycode 域名代码
- querystring 查询字符串
- readline 逐行读取
- repl 交互式解释器
- report 诊断报告
- stream 流
- stream/web 网络流
- string_decoder 字符串解码器
- test 测试
- timers 定时器
- tls 安全传输层
- trace_events 跟踪事件
- tty 终端
- url 网址
- util 实用工具
- v8 引擎
- vm 虚拟机
- wasi 网络汇编系统接口
- worker_threads 工作线程
- zlib 压缩
- 其他版本
C++ 嵌入器 API#
¥C++ embedder API
Node.js 提供了许多 C++ API,可用于在 Node.js 环境中从其他 C++ 软件执行 JavaScript。
¥Node.js provides a number of C++ APIs that can be used to execute JavaScript in a Node.js environment from other C++ software.
这些 API 的文档可以在 Node.js 源代码树的 src/node.h 中找到。除了 Node.js 暴露的 API,V8 嵌入器 API 还提供了一些必需的概念。
¥The documentation for these APIs can be found in src/node.h in the Node.js source tree. In addition to the APIs exposed by Node.js, some required concepts are provided by the V8 embedder API.
由于将 Node.js 用作嵌入式库不同于编写由 Node.js 执行的代码,因此重大更改不遵循典型的 Node.js 弃用政策,并且可能会在每个语义化版本主要版本中发生,而不会事先触发警告。
¥Because using Node.js as an embedded library is different from writing code that is executed by Node.js, breaking changes do not follow typical Node.js deprecation policy and may occur on each semver-major release without prior warning.
嵌入应用示例#
¥Example embedding application
以下章节将概述如何使用这些 API 从头开始创建应用,该应用将执行相当于 node -e <code>
的操作,也就是将使用一段 JavaScript 并在特定于 Node.js 的环境中运行。
¥The following sections will provide an overview over how to use these APIs
to create an application from scratch that will perform the equivalent of
node -e <code>
, i.e. that will take a piece of JavaScript and run it in
a Node.js-specific environment.
完整的代码可以在 在 Node.js 源代码树中 中找到。
¥The full code can be found in the Node.js source tree.
设置每个进程状态#
¥Setting up per-process state
Node.js 需要一些每个进程的状态管理才能运行:
¥Node.js requires some per-process state management in order to run:
-
Node.js CLI 选项 的参数解析,
¥Arguments parsing for Node.js CLI options,
-
V8 每个进程要求,例如
v8::Platform
实例。¥V8 per-process requirements, such as a
v8::Platform
instance.
下面的示例展示了如何设置这些。一些类名分别来自 node
和 v8
C++ 命名空间。
¥The following example shows how these can be set up. Some class names are from
the node
and v8
C++ namespaces, respectively.
int main(int argc, char** argv) {
argv = uv_setup_args(argc, argv);
std::vector<std::string> args(argv, argv + argc);
std::vector<std::string> exec_args;
std::vector<std::string> errors;
// Parse Node.js CLI options, and print any errors that have occurred while
// trying to parse them.
int exit_code = node::InitializeNodeWithArgs(&args, &exec_args, &errors);
for (const std::string& error : errors)
fprintf(stderr, "%s: %s\n", args[0].c_str(), error.c_str());
if (exit_code != 0) {
return exit_code;
}
// Create a v8::Platform instance. `MultiIsolatePlatform::Create()` is a way
// to create a v8::Platform instance that Node.js can use when creating
// Worker threads. When no `MultiIsolatePlatform` instance is present,
// Worker threads are disabled.
std::unique_ptr<MultiIsolatePlatform> platform =
MultiIsolatePlatform::Create(4);
V8::InitializePlatform(platform.get());
V8::Initialize();
// See below for the contents of this function.
int ret = RunNodeInstance(platform.get(), args, exec_args);
V8::Dispose();
V8::ShutdownPlatform();
return ret;
}
每个实例状态#
¥Per-instance state
Node.js 有一个“Node.js 实例”的概念,通常称为 node::Environment
。每个 node::Environment
都与:
¥Node.js has a concept of a “Node.js instance”, that is commonly being referred
to as node::Environment
. Each node::Environment
is associated with:
-
正好是
v8::Isolate
,即 JS 引擎实例,¥Exactly one
v8::Isolate
, i.e. one JS Engine instance, -
正好是
uv_loop_t
,即事件循环,并且¥Exactly one
uv_loop_t
, i.e. one event loop, and -
多个
v8::Context
,但恰好是一个主v8::Context
。¥A number of
v8::Context
s, but exactly one mainv8::Context
. -
一个
node::IsolateData
实例包含可由使用相同v8::Isolate
的多个node::Environment
共享的信息。目前,没有针对此场景执行测试。¥One
node::IsolateData
instance that contains information that could be shared by multiplenode::Environment
s that use the samev8::Isolate
. Currently, no testing if performed for this scenario.
为了设置 v8::Isolate
,需要提供 v8::ArrayBuffer::Allocator
。一种可能的选择是默认的 Node.js 分配器,它可以通过 node::ArrayBufferAllocator::Create()
创建。当插件使用 Node.js C++ Buffer
API 时,使用 Node.js 分配器可以实现较小的性能优化,并且需要在 process.memoryUsage()
中跟踪 ArrayBuffer
内存。
¥In order to set up a v8::Isolate
, an v8::ArrayBuffer::Allocator
needs
to be provided. One possible choice is the default Node.js allocator, which
can be created through node::ArrayBufferAllocator::Create()
. Using the Node.js
allocator allows minor performance optimizations when addons use the Node.js
C++ Buffer
API, and is required in order to track ArrayBuffer
memory in
process.memoryUsage()
.
此外,每个用于 Node.js 实例的 v8::Isolate
都需要在 MultiIsolatePlatform
实例中注册和注销(如果正在使用),以便平台知道对于 v8::Isolate
调度的任务使用哪个事件循环。
¥Additionally, each v8::Isolate
that is used for a Node.js instance needs to
be registered and unregistered with the MultiIsolatePlatform
instance, if one
is being used, in order for the platform to know which event loop to use
for tasks scheduled by the v8::Isolate
.
node::NewIsolate()
辅助函数创建 v8::Isolate
,使用一些 Node.js 特定的钩子(例如 Node.js 错误句柄)设置,并自动将其注册到平台。
¥The node::NewIsolate()
helper function creates a v8::Isolate
,
sets it up with some Node.js-specific hooks (e.g. the Node.js error handler),
and registers it with the platform automatically.
int RunNodeInstance(MultiIsolatePlatform* platform,
const std::vector<std::string>& args,
const std::vector<std::string>& exec_args) {
int exit_code = 0;
// Setup up a libuv event loop, v8::Isolate, and Node.js Environment.
std::vector<std::string> errors;
std::unique_ptr<CommonEnvironmentSetup> setup =
CommonEnvironmentSetup::Create(platform, &errors, args, exec_args);
if (!setup) {
for (const std::string& err : errors)
fprintf(stderr, "%s: %s\n", args[0].c_str(), err.c_str());
return 1;
}
Isolate* isolate = setup->isolate();
Environment* env = setup->env();
{
Locker locker(isolate);
Isolate::Scope isolate_scope(isolate);
HandleScope handle_scope(isolate);
// The v8::Context needs to be entered when node::CreateEnvironment() and
// node::LoadEnvironment() are being called.
Context::Scope context_scope(setup->context());
// Set up the Node.js instance for execution, and run code inside of it.
// There is also a variant that takes a callback and provides it with
// the `require` and `process` objects, so that it can manually compile
// and run scripts as needed.
// The `require` function inside this script does *not* access the file
// system, and can only load built-in Node.js modules.
// `module.createRequire()` is being used to create one that is able to
// load files from the disk, and uses the standard CommonJS file loader
// instead of the internal-only `require` function.
MaybeLocal<Value> loadenv_ret = node::LoadEnvironment(
env,
"const publicRequire ="
" require('node:module').createRequire(process.cwd() + '/');"
"globalThis.require = publicRequire;"
"require('node:vm').runInThisContext(process.argv[1]);");
if (loadenv_ret.IsEmpty()) // There has been a JS exception.
return 1;
exit_code = node::SpinEventLoop(env).FromMaybe(1);
// node::Stop() can be used to explicitly stop the event loop and keep
// further JavaScript from running. It can be called from any thread,
// and will act like worker.terminate() if called from another thread.
node::Stop(env);
}
return exit_code;
}