Node.js v18.18.0 文档

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

每个 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)#

如果选择此选项，ICU 将被禁用，并且上面提到的大多数国际化功能将在生成的 node 二进制文件中为 unavailable。

英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) 构建#

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)#

此选项静态地生成针对 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 数据#

如果使用 small-icu 选项，则仍然可以在运行时提供额外的语言环境数据，以便 JS 方法适用于所有 ICU 语言环境。 假设数据文件存储在 /some/directory，它可以通过以下任一方式提供给 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 /some/directory, it can be made available to ICU through either:

• NODE_ICU_DATA 环境变量：

  env NODE_ICU_DATA=/some/directory node 拷贝

• --icu-data-dir 命令行参数：

  node --icu-data-dir=/some/directory 拷贝

（如果两者都指定，则 --icu-data-dir 命令行参数优先。）

英(If both are specified, the --icu-data-dir CLI parameter takes precedence.)

ICU 能够自动查找和加载多种数据格式，但数据必须适合 ICU 版本，并且文件命名正确。 数据文件最常见的名称是 icudt6X[bl].dat，其中 6X 表示预期的 ICU 版本，而 b 或 l 表示系统的字节序。 查看 ICU 用户指南中的 "ICU 数据" 文章，了解其他支持的格式以及有关 ICU 数据的更多详细信息。

英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 icudt6X[bl].dat, where 6X denotes the intended ICU version, and b or l indicates the system's endianness. 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)#

此选项使生成的二进制链接与 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.

检测国际化支持#

要验证是否启用了 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 的部分。