Настройка отслеживания файлов

Начиная с TypeScript 3.8 и далее, компилятор TypeScript предоставляет конфигурацию, которая контролирует, как он отслеживает файлы и каталоги. До этой версии конфигурация требовала использования переменных окружения, которые по-прежнему доступны.

Обзор

Реализация компилятора --watch опирается на методы Node’s fs.watch и fs.watchFile. Каждый из этих методов имеет свои преимущества и недостатки.

fs.watch полагается на события файловой системы для трансляции изменений в отслеживаемых файлах и каталогах. Реализация этой команды зависит от ОС и может быть ненадежной — во многих операционных системах она не работает как ожидается. Кроме того, некоторые операционные системы ограничивают количество одновременно существующих отслеживаний (например, некоторые варианты Linux). Активное использование fs.watch в больших кодовых базах может превысить эти ограничения и привести к нежелательному поведению. Однако, поскольку эта реализация основана на модели событий, использование процессора относительно невелико. Компилятор обычно использует fs.watch для отслеживания каталогов (например, каталоги источников, включенные файлами конфигурации компилятора, и каталоги, в которых произошел сбой разрешения модулей, среди прочих). TypeScript использует их для дополнения потенциальных ошибок в индивидуальных файловых наблюдателях. Однако существует ключевое ограничение этой стратегии: рекурсивное отслеживание каталогов поддерживается в Windows и macOS, но не в Linux. Это потребовало разработки дополнительных стратегий для отслеживания файлов и каталогов.

fs.watchFile использует опросный метод и, следовательно, расходует циклы процессора. Однако fs.watchFile является, пожалуй, наиболее надежным механизмом для подписки на события из файлов и каталогов, которые нас интересуют. В рамках этой стратегии компилятор TypeScript обычно использует fs.watchFile для отслеживания исходных файлов, файлов конфигурации и файлов, которые, по-видимому, отсутствуют на основании ссылочных утверждений. Это означает, что степень повышения использования процессора при использовании fs.watchFile напрямую зависит от количества отслеживаемых файлов в кодовой базе.

Настройка отслеживания файлов с помощью tsconfig.json

Рекомендуемый метод настройки поведения отслеживания — через новый раздел watchOptions в файле tsconfig.json. Ниже приведен пример конфигурации. Подробные описания доступных настроек см. в следующем разделе.

{
  // 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

Настройка отслеживания каталогов с помощью переменной окружения TSC_WATCHDIRECTORY

Для отслеживания каталогов на платформах, которые не поддерживают рекурсивное отслеживание каталогов по умолчанию (то есть, не macOS и Windows), используется рекурсивное создание наблюдателей каталогов для каждого подкаталога с использованием различных параметров, выбранных в TSC_WATCHDIRECTORY.

ПРИМЕЧАНИЕ: На платформах, которые поддерживают рекурсивное отслеживание каталогов по умолчанию, значение TSC_WATCHDIRECTORY игнорируется.