設定監控

從 TypeScript 3.8 開始，TypeScript 編譯器公開了控制其監控檔案和目錄方式的組態。在此版本之前，組態需要使用環境變數，這些變數仍然可用。

背景

編譯器的 --watch 實作仰賴 Node 的 fs.watch 和 fs.watchFile。這些方法各有優缺點。

fs.watch 依賴檔案系統事件來廣播受監控檔案和目錄中的變更。此命令的實作取決於作業系統且不可靠，在許多作業系統上，其運作方式並非預期的那樣。此外，有些作業系統會限制同時存在的監控數量（例如某些版本的 Linux）。在大型程式碼庫中大量使用 fs.watch 可能會超過這些限制，並導致不必要的行為。然而，由於此實作依賴於基於事件的模型，因此 CPU 使用率相對較低。編譯器通常使用 fs.watch 來監控目錄（例如編譯器組態檔包含的來源目錄和模組解析失敗的目錄等）。TypeScript 使用這些來擴充個別檔案監控器中的潛在失敗。然而，此策略有一個主要的限制：在 Windows 和 macOS 上支援目錄的遞迴監控，但在 Linux 上不支援。這表示需要針對檔案和目錄監控採取其他策略。

fs.watchFile 使用輪詢，因此會消耗 CPU 週期。然而，fs.watchFile 是目前訂閱感興趣檔案和目錄事件最可靠的機制。在此策略下，TypeScript 編譯器通常使用 fs.watchFile 來監控來源檔案、組態檔和根據參考陳述看來遺失的檔案。這表示使用 fs.watchFile 時 CPU 使用率會增加的程度直接取決於程式碼庫中受監控的檔案數量。

使用 tsconfig.json 設定檔案監控

建議透過 tsconfig.json 中新的 watchOptions 區段來設定監控行為。我們在下方提供範例設定。有關可用設定的詳細說明，請參閱下列區段。

{
  // Some typical compiler options
  "compilerOptions": {
    "target": "es2020",
    "moduleResolution": "node"
    // ...
  },
  // NEW: Options for file/directory watching
  "watchOptions": {
    // Use native file system events for files and directories
    "watchFile": "useFsEvents",
    "watchDirectory": "useFsEvents",
    // Poll files for updates more frequently
    // when they're updated a lot.
    "fallbackPolling": "dynamicPriority",
    // Don't coalesce watch notification
    "synchronousWatchDirectory": true,
    // Finally, two additional settings for reducing the amount of possible
    // files to track  work from these directories
    "excludeDirectories": ["**/node_modules", "_build"],
    "excludeFiles": ["build/fileWhichChangesOften.ts"]
  }
}

如需更多詳細資料，請參閱 Typescript 3.8 的發行說明。

使用環境變數 TSC_WATCHFILE 設定檔案監控

選項	說明
PriorityPollingInterval	使用 fs.watchFile，但對原始檔、設定檔和遺失檔使用不同的輪詢間隔
DynamicPriorityPolling	使用動態佇列，其中頻繁修改的檔案會以較短的間隔進行輪詢，而未變更的檔案則會以較不頻繁的間隔進行輪詢
UseFsEvents	使用 `fs.watch`。在限制活動監控器數量的作業系統上，當無法建立監控器時，改用 `fs.watchFile`。
UseFsEventsWithFallbackDynamicPolling	使用 `fs.watch`。在限制活動監控器數量的作業系統上，改用動態輪詢佇列（如 `DynamicPriorityPolling` 中所述）
UseFsEventsOnParentDirectory	在所包含檔案的父目錄上使用 `fs.watch`（達成折衷，結果比純粹的 `fs.watchFile` 降低 CPU 使用率，但準確度可能較低）。
預設（未指定值）	如果環境變數 `TSC_NONPOLLING_WATCHER` 設為 true，請使用 `UseFsEventsOnParentDirectory`。否則，使用 `fs.watchFile` 監控檔案，並將任何檔案的逾時設為 `250ms`。

使用環境變數 `TSC_WATCHDIRECTORY` 設定目錄監控

在原生不允許遞迴目錄監控的平台（即非 macOS 和 Windows 作業系統）上進行目錄監控，支援透過遞迴建立目錄監控器，針對每個子目錄使用 `TSC_WATCHDIRECTORY` 選擇的不同選項。

注意：在支援原生遞迴目錄監控的平台上，`TSC_WATCHDIRECTORY` 的值會被忽略。

選項	說明
使用 FsWatchFile 的遞迴目錄	使用 fs.watchFile 來監控包含的目錄和子目錄。
使用動態優先級輪詢的遞迴目錄	使用動態輪詢佇列來輪詢包含的目錄和子目錄的變更。
預設（未指定值）	使用 fs.watch 來監控包含的目錄和子目錄。