配置監視模式

從 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 使用率更低，但準確性可能較低）。
default (未指定值)	如果環境變數 TSC_NONPOLLING_WATCHER 設定為 true，則使用 UseFsEventsOnParentDirectory。否則，使用 fs.watchFile 監視檔案，並將 250ms 作為任何檔案的超時時間。

使用環境變數 TSC_WATCHDIRECTORY 配置目錄監視

對於原生不支援遞迴目錄監視的平臺（即非 macOS 和 Windows 作業系統）上的目錄監視，支援透過使用 TSC_WATCHDIRECTORY 選擇的不同選項，為每個子目錄遞迴建立目錄監視器。

注意： 在支援原生遞迴目錄監視的平臺上，TSC_WATCHDIRECTORY 的值將被忽略。

選項	描述
RecursiveDirectoryUsingFsWatchFile	使用 fs.watchFile 監視包含的目錄和子目錄。
RecursiveDirectoryUsingDynamicPriorityPolling	使用動態輪詢佇列來輪詢包含的目錄和子目錄的變更。
default (未指定值)	使用 fs.watch 來監視包含的目錄和子目錄。