- 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 包模块
- module/typescript TS 模块
- net 网络
- os 操作系统
- path 路径
- perf_hooks 性能钩子
- permission 权限
- process 进程
- punycode 域名代码
- querystring 查询字符串
- readline 逐行读取
- repl 交互式解释器
- report 诊断报告
- sea 单个可执行应用程序
Node.js v22.11.0 文档
- Node.js v22.11.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 包模块
- module/typescript TS 模块
- net 网络
- os 操作系统
- path 路径
- perf_hooks 性能钩子
- permission 权限
- process 进程
- punycode 域名代码
- querystring 查询字符串
- readline 逐行读取
- repl 交互式解释器
- report 诊断报告
- sea 单个可执行应用程序
- 其他版本
国际化支持#
¥Internationalization support
Node.js 有很多特性可以让编写国际化程序变得更容易。它们之中有一些是:
¥Node.js has many features that make it easier to write internationalized programs. Some of them are:
-
ECMAScript 语言规范 中的语言环境敏感或 Unicode 感知函数:
¥Locale-sensitive or Unicode-aware functions in the ECMAScript Language Specification:
-
ECMAScript 国际化 API 规范(又名 ECMA-402)中描述的所有功能:
¥All functionality described in the ECMAScript Internationalization API Specification (aka ECMA-402):
-
Intl
对象¥
Intl
object -
像
String.prototype.localeCompare()
和Date.prototype.toLocaleString()
这样的区域敏感方法¥Locale-sensitive methods like
String.prototype.localeCompare()
andDate.prototype.toLocaleString()
-
-
WHATWG URL 解析器 的 国际化域名 (IDNs) 支持
¥The WHATWG URL parser's internationalized domain names (IDNs) support
-
更准确的 REPL 行编辑
¥More accurate REPL line editing
Node.js 和底层 V8 引擎使用 Unicode 国际组件 (ICU) 在原生 C/C++ 代码中实现这些功能。默认情况下,Node.js 提供了完整的 ICU 数据集。但是,由于 ICU 数据文件的大小,在构建或运行 Node.js 时提供了几个用于自定义 ICU 数据集的选项。
¥Node.js and the underlying V8 engine use International Components for Unicode (ICU) to implement these features in native C/C++ code. The full ICU data set is provided by Node.js by default. However, due to the size of the ICU data file, several options are provided for customizing the ICU data set either when building or running Node.js.
构建 Node.js 的选项#
¥Options for building Node.js
为了控制在 Node.js 中如何使用 ICU,在编译期间提供了四个 configure
选项。BUILDING.md 中记录了有关如何编译 Node.js 的其他详细信息。
¥To control how ICU is used in Node.js, four configure
options are available
during compilation. Additional details on how to compile Node.js are documented
in BUILDING.md.
-
--with-intl=none
/--without-intl
-
--with-intl=system-icu
-
--with-intl=small-icu
-
--with-intl=full-icu
(默认)¥
--with-intl=full-icu
(default)
每个 configure
选项的可用 Node.js 和 JavaScript 特性概述:
¥An overview of available Node.js and JavaScript features for each configure
option:
特性 | none | system-icu | small-icu | full-icu |
---|---|---|---|---|
String.prototype.normalize() | 无(函数无操作) | 完全 | 完全 | 完全 |
String.prototype.to*Case() | 完全 | 完全 | 完全 | 完全 |
Intl | 无(对象不存在) | 部分/完整(取决于操作系统) | 部分(仅限英语) | 完全 |
String.prototype.localeCompare() | 部分(不识别区域设置) | 完全 | 完全 | 完全 |
String.prototype.toLocale*Case() | 部分(不识别区域设置) | 完全 | 完全 | 完全 |
Number.prototype.toLocaleString() | 部分(不识别区域设置) | 部分/完整(取决于操作系统) | 部分(仅限英语) | 完全 |
Date.prototype.toLocale*String() | 部分(不识别区域设置) | 部分/完整(取决于操作系统) | 部分(仅限英语) | 完全 |
旧版 URL 解析器 | 部分(不支持 IDN) | 完全 | 完全 | 完全 |
WHATWG URL 解析器 | 部分(不支持 IDN) | 完全 | 完全 | 完全 |
require('node:buffer').transcode() | 无(函数不存在) | 完全 | 完全 | 完全 |
REPL | 部分(行编辑不准确) | 完全 | 完全 | 完全 |
require('node:util').TextDecoder | 部分(基本编码支持) | 部分/完整(取决于操作系统) | 部分(仅限 Unicode) | 完全 |
RegExp Unicode 属性转义 | 无(无效 RegExp 错误) | 完全 | 完全 | 完全 |
"(不识别区域设置)" 标志表示该函数执行其操作就像该函数的非 Locale
版本(如果存在)一样。比如在 none
模式下,Date.prototype.toLocaleString()
的操作和 Date.prototype.toString()
是一样的。
¥The "(not locale-aware)" designation denotes that the function carries out its
operation just like the non-Locale
version of the function, if one
exists. For example, under none
mode, Date.prototype.toLocaleString()
's
operation is identical to that of Date.prototype.toString()
.
禁用所有国际化功能 (none
)#
¥Disable all internationalization features (none
)
如果选择此选项,ICU 将被禁用,并且上述大多数国际化功能在生成的 node
二进制文件中将不可用。
¥If this option is chosen, ICU is disabled and most internationalization
features mentioned above will be unavailable in the resulting node
binary.
使用预装的 ICU (system-icu
) 构建#
¥Build with a pre-installed ICU (system-icu
)
Node.js 可以链接到系统上已安装的 ICU。事实上,大多数 Linux 发行版已经安装了 ICU,这个选项可以复用操作系统中其他组件使用的相同数据集。
¥Node.js can link against an ICU build already installed on the system. In fact, most Linux distributions already come with ICU installed, and this option would make it possible to reuse the same set of data used by other components in the OS.
system-icu
完全支持仅需要 ICU 库本身的功能,例如 String.prototype.normalize()
和 WHATWG URL 解析器。另外需要 ICU 区域设置数据的功能,例如 Intl.DateTimeFormat
,可能会得到完全或部分支持,具体取决于安装在系统上的 ICU 数据的完整性。
¥Functionalities that only require the ICU library itself, such as
String.prototype.normalize()
and the WHATWG URL parser, are fully
supported under system-icu
. Features that require ICU locale data in
addition, such as Intl.DateTimeFormat
may be fully or partially
supported, depending on the completeness of the ICU data installed on the
system.
嵌入一组有限的 ICU 数据 (small-icu
)#
¥Embed a limited set of ICU data (small-icu
)
此选项静态地生成针对 ICU 库的二进制链接,并在 node
可执行文件中包含 ICU 数据的子集(通常只有英文区域设置)。
¥This option makes the resulting binary link against the ICU library statically,
and includes a subset of ICU data (typically only the English locale) within
the node
executable.
small-icu
完全支持仅需要 ICU 库本身的功能,例如 String.prototype.normalize()
和 WHATWG URL 解析器。另外需要 ICU 语言环境数据的特性,比如 Intl.DateTimeFormat
,一般只适用于英文语言环境:
¥Functionalities that only require the ICU library itself, such as
String.prototype.normalize()
and the WHATWG URL parser, are fully
supported under small-icu
. Features that require ICU locale data in addition,
such as Intl.DateTimeFormat
, generally only work with the English locale:
const january = new Date(9e8);
const english = new Intl.DateTimeFormat('en', { month: 'long' });
const spanish = new Intl.DateTimeFormat('es', { month: 'long' });
console.log(english.format(january));
// Prints "January"
console.log(spanish.format(january));
// Prints either "M01" or "January" on small-icu, depending on the user’s default locale
// Should print "enero"
此模式提供了特性和二进制大小之间的平衡。
¥This mode provides a balance between features and binary size.
在运行时提供 ICU 数据#
¥Providing ICU data at runtime
如果使用 small-icu
选项,则仍然可以在运行时提供额外的语言环境数据,以便 JS 方法适用于所有 ICU 语言环境。假设数据文件存储在 /runtime/directory/with/dat/file
,它可以通过以下任一方式提供给 ICU:
¥If the small-icu
option is used, one can still provide additional locale data
at runtime so that the JS methods would work for all ICU locales. Assuming the
data file is stored at /runtime/directory/with/dat/file
, it can be made
available to ICU through either:
-
--with-icu-default-data-dir
配置选项:¥The
--with-icu-default-data-dir
configure option:./configure --with-icu-default-data-dir=/runtime/directory/with/dat/file --with-intl=small-icu
这仅将默认数据目录路径嵌入到二进制文件中。实际的数据文件将在运行时从此目录路径加载。
¥This only embeds the default data directory path into the binary. The actual data file is going to be loaded at runtime from this directory path.
-
NODE_ICU_DATA
环境变量:¥The
NODE_ICU_DATA
environment variable:env NODE_ICU_DATA=/runtime/directory/with/dat/file node
-
--icu-data-dir
命令行参数:¥The
--icu-data-dir
CLI parameter:node --icu-data-dir=/runtime/directory/with/dat/file
当指定多个变量时,--icu-data-dir
CLI 参数具有最高优先级,然后是 NODE_ICU_DATA
环境变量,最后是 --with-icu-default-data-dir
配置选项。
¥When more than one of them is specified, the --icu-data-dir
CLI parameter has
the highest precedence, then the NODE_ICU_DATA
environment variable, then
the --with-icu-default-data-dir
configure option.
ICU 能够自动查找和加载多种数据格式,但数据必须适合 ICU 版本,并且文件命名正确。数据文件最常见的名称是 icudtX[bl].dat
,其中 X
表示预期的 ICU 版本,而 b
或 l
表示系统的字节序。如果无法从指定目录读取预期的数据文件,Node.js 将无法加载。与当前 Node.js 版本对应的数据文件的名称可以通过以下方式计算:
¥ICU is able to automatically find and load a variety of data formats, but the
data must be appropriate for the ICU version, and the file correctly named.
The most common name for the data file is icudtX[bl].dat
, where X
denotes
the intended ICU version, and b
or l
indicates the system's endianness.
Node.js would fail to load if the expected data file cannot be read from the
specified directory. The name of the data file corresponding to the current
Node.js version can be computed with:
`icudt${process.versions.icu.split('.')[0]}${os.endianness()[0].toLowerCase()}.dat`;
查看 ICU 用户指南中的 "ICU 数据" 文章,了解其他支持的格式以及有关 ICU 数据的更多详细信息。
¥Check "ICU Data" article in the ICU User Guide for other supported formats and more details on ICU data in general.
full-icu npm 模块可以通过检测正在运行的 node
可执行文件的 ICU 版本并下载适当的数据文件来极大地简化 ICU 数据安装。通过 npm i full-icu
安装模块后,数据文件将在 ./node_modules/full-icu
可用。然后可以将此路径传给 NODE_ICU_DATA
或 --icu-data-dir
,如上所示以启用完整的 Intl
支持。
¥The full-icu npm module can greatly simplify ICU data installation by
detecting the ICU version of the running node
executable and downloading the
appropriate data file. After installing the module through npm i full-icu
,
the data file will be available at ./node_modules/full-icu
. This path can be
then passed either to NODE_ICU_DATA
or --icu-data-dir
as shown above to
enable full Intl
support.
嵌入整个 ICU (full-icu
)#
¥Embed the entire ICU (full-icu
)
此选项使生成的二进制链接与 ICU 静态地关联并包含全套 ICU 数据。以这种方式创建的二进制文件没有进一步的外部依赖并支持所有语言环境,但可能相当大。如果没有传入 --with-intl
标志,则这是默认行为。官方的二进制文件也是以这种模式构建的。
¥This option makes the resulting binary link against ICU statically and include
a full set of ICU data. A binary created this way has no further external
dependencies and supports all locales, but might be rather large. This is
the default behavior if no --with-intl
flag is passed. The official binaries
are also built in this mode.
检测国际化支持#
¥Detecting internationalization support
要验证是否启用了 ICU(system-icu
、small-icu
或 full-icu
),只需检查 Intl
是否存在就足够了:
¥To verify that ICU is enabled at all (system-icu
, small-icu
, or
full-icu
), simply checking the existence of Intl
should suffice:
const hasICU = typeof Intl === 'object';
或者,检查 process.versions.icu
,一个仅在启用 ICU 时定义的属性,也可以工作:
¥Alternatively, checking for process.versions.icu
, a property defined only
when ICU is enabled, works too:
const hasICU = typeof process.versions.icu === 'string';
要检查对非英语语言环境(即 full-icu
或 system-icu
)的支持,Intl.DateTimeFormat
可能是一个很好的区分因素:
¥To check for support for a non-English locale (i.e. full-icu
or
system-icu
), Intl.DateTimeFormat
can be a good distinguishing factor:
const hasFullICU = (() => {
try {
const january = new Date(9e8);
const spanish = new Intl.DateTimeFormat('es', { month: 'long' });
return spanish.format(january) === 'enero';
} catch (err) {
return false;
}
})();
有关 Intl
支持的更详细的测试,以下资源可能会有所帮助:
¥For more verbose tests for Intl
support, the following resources may be found
to be helpful: