Node.js v22.22.0 文档

构建 Node.js 的选项#>

【Options for building Node.js】

要控制 Node.js 中 ICU 的使用，在编译过程中可以使用四个 configure 选项。有关如何编译 Node.js 的更多详细信息，请参见 BUILDING.md。

【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（默认）

每个 configure 选项可用的 Node.js 和 JavaScript 功能概览：

【An overview of available Node.js and JavaScript features for each configure option:】

“（非地区感知）”的标记表示该函数的操作方式与非 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.】

仅需要 ICU 库本身的功能，例如 String.prototype.normalize() 和 WHATWG URL 解析器，在 system-icu 下是完全支持的。需要 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.】

仅需要 ICU 库本身的功能，例如 String.prototype.normalize() 和 WHATWG URL 解析器，在 small-icu 下完全支持。需要额外的 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 配置选项：

  ./configure --with-icu-default-data-dir=/runtime/directory/with/dat/file --with-intl=small-icu 拷贝

  这只会将默认的数据目录路径嵌入到二进制文件中。实际的数据文件将在运行时从该目录路径加载。

• NODE_ICU_DATA 环境变量：

  env NODE_ICU_DATA=/runtime/directory/with/dat/file node 拷贝

• --icu-data-dir CLI 参数：

  node --icu-data-dir=/runtime/directory/with/dat/file 拷贝

当指定多个选项时，--icu-data-dir 命令行参数具有最高优先级，其次是 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 数据的一般详细信息。

【Check "ICU Data" article in the ICU User Guide for other supported formats and more details on ICU data in general.】

完整 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:】

• btest402：通常用于检查是否正确构建了带有 Intl 支持的 Node.js。
• Test262：ECMAScript 的官方一致性测试套件包含一个专门针对 ECMA-402 的部分。