Node.js v21.7.2 文件

建置 Node.js 的選項#

若要控制 ICU 在 Node.js 中的使用方式，編譯期間有四個可用的 configure 選項。有關如何編譯 Node.js 的其他詳細資訊記錄在 BUILDING.md 中。

• --with-intl=none/--without-intl
• --with-intl=system-icu
• --with-intl=small-icu
• --with-intl=full-icu (預設)

每個 configure 選項可用的 Node.js 和 JavaScript 功能概觀

「(不具備區域感知)」標示表示函式會執行其作業，就像函式的非 Locale 版本一樣，如果有的話。例如，在 none 模式下，Date.prototype.toLocaleString() 的作業與 Date.prototype.toString() 相同。

停用所有國際化功能 (none)#

如果選擇此選項，ICU 會停用，而上述大部分國際化功能在產生的 node 二進位檔中將會不可用。

使用預先安裝的 ICU (system-icu) 建置#

Node.js 可以連結到系統上已安裝的 ICU 建置。事實上，大多數 Linux 發行版都已經安裝 ICU，而此選項將讓系統中其他元件能重複使用同一組資料。

僅需要 ICU 函式庫本身的功能，例如 String.prototype.normalize() 和 WHATWG URL parser，在 system-icu 下獲得完全支援。此外，需要 ICU 地區資料的功能，例如 Intl.DateTimeFormat，可能會獲得完全或部分支援，具體取決於系統上安裝的 ICU 資料的完整性。

嵌入有限的 ICU 資料組 (small-icu)#

此選項會讓產生的二進位檔靜態連結到 ICU 函式庫，並在 node 可執行檔中包含 ICU 資料的子集（通常僅包含英文地區資料）。

僅需要 ICU 函式庫本身的功能，例如 String.prototype.normalize() 和 WHATWG URL parser，在 small-icu 下獲得完全支援。此外，需要 ICU 地區資料的功能，例如 Intl.DateTimeFormat，通常僅能使用英文地區資料

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" copy

此模式在功能和二進位檔大小之間取得平衡。

在執行階段提供 ICU 資料#

如果使用 small-icu 選項，您仍可在執行階段提供其他地區資料，讓 JS 方法適用於所有 ICU 地區。假設資料檔案儲存在 /runtime/directory/with/dat/file，則可透過下列方式讓 ICU 使用：

• --with-icu-default-data-dir 設定選項

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

  這只會將預設資料目錄路徑內嵌到二進位檔中。實際的資料檔案將在執行階段從這個目錄路徑載入。

• NODE_ICU_DATA 環境變數

  env NODE_ICU_DATA=/runtime/directory/with/dat/file node copy

• --icu-data-dir CLI 參數

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

如果指定多個參數，--icu-data-dir CLI 參數優先權最高，其次為 NODE_ICU_DATA 環境變數，最後為 --with-icu-default-data-dir 設定選項。

ICU 可以自動尋找並載入各種資料格式，但資料必須符合 ICU 版本，且檔案必須正確命名。資料檔案最常見的名稱是 icudtX[bl].dat，其中 X 表示預期的 ICU 版本，而 b 或 l 表示系統的位元序。如果無法從指定的目錄讀取預期的資料檔案，Node.js 將載入失敗。對應於目前 Node.js 版本的資料檔案名稱可透過下列方式計算：

`icudt${process.versions.icu.split('.')[0]}${os.endianness()[0].toLowerCase()}.dat`; copy

請查看 ICU 使用者指南中的 "ICU 資料" 文章，以了解其他支援的格式和有關一般 ICU 資料的更多詳細資訊。

npm 模組 full-icu 透過偵測執行中 node 可執行檔的 ICU 版本，並下載適當的資料檔，大幅簡化 ICU 資料的安裝。透過 npm i full-icu 安裝模組後，資料檔將會在 ./node_modules/full-icu 中。此路徑接著可以傳遞到 NODE_ICU_DATA 或 --icu-data-dir，如上所示，以啟用完整的 Intl 支援。

內嵌整個 ICU (full-icu)#

此選項會讓產生的二進位檔靜態連結到 ICU，並包含一組完整的 ICU 資料。以此方式建立的二進位檔沒有其他外部相依性，並支援所有語言環境，但可能會相當大。如果沒有傳遞 --with-intl 旗標，這是預設行為。官方二進位檔也以此模式建立。

偵測國際化支援#

要驗證 ICU 是否已啟用（system-icu、small-icu 或 full-icu），只需檢查 Intl 的存在即可

const hasICU = typeof Intl === 'object'; copy

或者，檢查 process.versions.icu（僅在啟用 ICU 時定義的屬性）也可以

const hasICU = typeof process.versions.icu === 'string'; copy

要檢查非英語語言環境的支援（例如 full-icu 或 system-icu），Intl.DateTimeFormat 可以是一個很好的區分因素

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;
  }
})(); copy

對於 Intl 支援的更詳細測試，下列資源可能會有幫助

• btest402：一般用於檢查支援 Intl 的 Node.js 是否正確建立。
• Test262：ECMAScript 的官方相符性測試套件包括一個專門針對 ECMA-402 的區段。