配置监视

从 TypeScript 3.8 版本开始，TypeScript 编译器提供了可以控制如何监视文件和目录的配置。在此版本之前，配置需要使用环境变量，这些变量仍然可用。

🌐 As of TypeScript 3.8 and onward, the Typescript compiler exposes configuration which controls how it watches files and directories. Prior to this version, configuration required the use of environment variables which are still available.

背景

🌐 Background

编译器的 --watch 实现依赖于 Node 的 fs.watch 和 fs.watchFile。每种方法都有其优缺点。

🌐 The --watch implementation of the compiler relies on Node’s fs.watch and fs.watchFile. Each of these methods has pros and cons.

fs.watch relies on file system events to broadcast changes in the watched files and directories. The implementation of this command is OS dependent and unreliable - on many operating systems, it does not work as expected. Additionally, some operating systems limit the number of watches which can exist simultaneously (e.g. some flavors of Linux). Heavy use of fs.watch in large codebases has the potential to exceed these limits and result in undesirable behavior. However, because this implementation relies on an events-based model, CPU use is comparatively light. The compiler typically uses fs.watch to watch directories (e.g. source directories included by compiler configuration files and directories in which module resolution failed, among others). TypeScript uses these to augment potential failures in individual file watchers. However, there is a key limitation of this strategy: recursive watching of directories is supported on Windows and macOS, but not on Linux. This suggested a need for additional strategies for file and directory watching.

fs.watchFile 使用轮询，因此会消耗 CPU 周期。然而，fs.watchFile 无疑是订阅感兴趣的文件和目录事件最可靠的机制。在这种策略下，TypeScript 编译器通常使用 fs.watchFile 来监视源文件、配置文件以及根据引用语句可能丢失的文件。这意味着使用 fs.watchFile 时 CPU 使用率的增加程度直接取决于代码库中被监视的文件数量。

使用 tsconfig.json 配置文件监控

🌐 Configuring file watching using a tsconfig.json

建议通过 tsconfig.json 的新 watchOptions 部分来配置 watch 行为。我们在下面提供了一个示例配置。有关可用设置的详细说明，请参见以下部分。

🌐 The suggested method of configuring watch behavior is through the new watchOptions section of tsconfig.json. We provide an example configuration below. See the following section for detailed descriptions of the settings available.

{
  // 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 的发行说明。

🌐 For further details, see the release notes for Typescript 3.8.

使用环境变量 TSC_WATCHFILE 配置文件监控

🌐 Configuring file watching using environment variable TSC_WATCHFILE

Option	Description
PriorityPollingInterval	Use fs.watchFile, but use different polling intervals for source files, config files and missing files
DynamicPriorityPolling	Use a dynamic queue where frequently modified files are polled at shorter intervals, and unchanged files are polled less frequently
UseFsEvents	Use fs.watch. On operating systems that limit the number of active watches, fall back to fs.watchFile when a watcher fails to be created.
UseFsEventsWithFallbackDynamicPolling	Use fs.watch. On operating systems that limit the number of active watches, fall back to dynamic polling queues (as explained in DynamicPriorityPolling)
UseFsEventsOnParentDirectory	Use fs.watch on the parent directories of included files (yielding a compromise that results in lower CPU usage than pure fs.watchFile but potentially lower accuracy).
default (no value specified)	If environment variable TSC_NONPOLLING_WATCHER is set to true, use UseFsEventsOnParentDirectory. Otherwise, watch files using fs.watchFile with 250ms as the timeout for any file.

使用环境变量 TSC_WATCHDIRECTORY 配置目录监控

🌐 Configuring directory watching using environment variable TSC_WATCHDIRECTORY

对于不原生支持递归目录监视的平台（即非 macOS 和 Windows 操作系统），可以通过使用 TSC_WATCHDIRECTORY 选择的不同选项，为每个子目录递归创建目录监视器来实现支持。

🌐 For directory watches on platforms which don’t natively allow recursive directory watching (i.e. non macOS and Windows operating systems) is supported through recursively creating directory watchers for each child directory using different options selected by TSC_WATCHDIRECTORY.

注意： 在支持本地递归目录监控的平台上，TSC_WATCHDIRECTORY 的值将被忽略。

选项	描述
RecursiveDirectoryUsingFsWatchFile	使用 fs.watchFile 来监视包含的目录及其子目录。
RecursiveDirectoryUsingDynamicPriorityPolling	使用动态轮询队列来轮询包含的目录及其子目录的更改。
default (未指定值)	使用 fs.watch 来监视包含的目录及其子目录。