配置监视模式

从 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 来监视包含的目录和子目录。