Автоматическое отслеживание данных

Автоматическое отслеживание данных — это механизм, с помощью которого Vite Task определяет, какие входные данные нужны задаче для кэширования результатов без явной настройки.

Когда вы запускаете задачу с включённым кэшированием, Vite Task отслеживает выполнение задачи и сохраняет информацию о прочитанных и записанных файлах, а также любые метаданные, переданные задачей. При следующем запуске Vite Task использует сохранённый отпечаток, чтобы определить, нужно ли использовать кэш или повторно выполнить задачу.

Используйте эту страницу, если вам нужно понять, почему задача использовала кэш или почему кэш был пропущен, а также если нужно решить, следует ли добавлять настройки input, output, env или untrackedEnv.

Уровни отслеживания

Автоматическое отслеживание данных имеет два уровня:

Уровень	Применяется к	Что отслеживается
Отслеживание файловой системы	Всем задачам с включённым кэшированием	Файлы, прочитанные командой Проверки отсутствующих файлов Содержимое списков каталогов Созданные выходные файлы
Кооперативное отслеживание	Инструментам, предоставляющим данные для кэша (vp build на данный момент)	Переменные окружения, переданные инструментом Пути, управляемые инструментом, которые не должны считаться входными или выходными данными, например node_modules/.vite-temp

Vite Task начинает с отслеживания файловой системы для любой команды. Инструмент, предоставляющий данные для кэша, может добавить информацию, известную только самому инструменту во время выполнения.

Отслеживание файловой системы

Отслеживание файловой системы применяется к каждой задаче с включённым кэшированием. Если вы не указываете input, Vite Task отслеживает файлы, которые команда читает во время выполнения:

vite.config.ts

import { defineConfig } from 'vite-plus';

export default defineConfig({
  run: {
    tasks: {
      build: {
        command: 'tsc',
      },
    },
  },
});

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

Отслеживание файловой системы также учитывает выходные данные. Если вы не указываете output, Vite Task архивирует файлы, созданные командой после успешного выполнения, и восстанавливает их при попадании в кэш.

Ограничения

Vite Task не может отслеживать чтение переменных окружения и не всегда может определить, какие из отслеживаемых путей являются стабильными входными данными, сгенерированными выходными файлами или управляемыми инструментом путями кэша, которые не должны становиться входными или выходными данными.

Используйте раздел Переопределение входных и выходных данных, если отслеживание файловой системы включает файлы, которые не должны влиять на кэш, не учитывает файлы, которые должны влиять на кэш, или восстанавливает неправильные выходные файлы.

Используйте env, если команде требуется переменная окружения и её значение должно влиять на кэш, либо untrackedEnv, если значение не должно влиять на кэш.

Эти ограничения не распространяются на vp build: Vite автоматически передаёт метаданные кооперативного отслеживания, включая VITE_*, NODE_ENV и управляемые Vite пути кэша, которые не должны становиться входными или выходными данными. Стандартная задача vp build не требует ручной настройки input, output или env.

Переопределение входных и выходных данных

input определяет, какие изменения приводят к инвалидированию кэша. output определяет, какие файлы Vite Task восстанавливает при попадании в кэш.

Обе настройки используют одинаковый синтаксис и могут конфигурироваться независимо друг от друга.

• Не указывайте параметр, чтобы сохранить автоматическое отслеживание.
• Добавьте { auto: true }, чтобы сохранить автоматическое отслеживание и одновременно добавить правила с glob-шаблонами.
• Используйте строковые glob-шаблоны для включения путей.
• Используйте glob-шаблоны с ! для исключения путей.
• Используйте [], чтобы заменить автоматическое отслеживание пустым списком.

vite.config.ts

tasks: {
  build: {
    command: 'node build.mjs',

    // Сохранить автоматическое отслеживание входных данных, но исключить `dist` из входов.
    input: [{ auto: true }, '!dist/**'],

    // Отключить автоматическое отслеживание выходных данных и восстанавливать только `dist/**` при попадании в кэш.
    output: ['dist/**'],
  },
}

Используйте явные glob-шаблоны для input только в том случае, если вы точно знаете полный набор входных данных команды. Эта задача линтинга переопределяет только входные данные, поэтому отслеживание выходных данных остаётся автоматическим:

vite.config.ts

tasks: {
  lint: {
    command: 'vp lint',
    // Отключить автоматическое отслеживание входных данных и учитывать в отпечатке только эти файлы.
    input: ['src/**', 'vite.config.ts'],
  },
}

Установите input: [], если никакие файлы не должны влиять на отпечаток кэша. Это требуется редко. Например, задача загрузки может использовать кэш, если один и тот же URL всегда возвращает один и тот же файл. Для такой задачи не нужно вычислять отпечаток по входным файлам, но изменение URL всё равно должно инвалидировать кэш:

vite.config.ts

tasks: {
  downloadSchema: {
    command: 'curl -O https://example.com/schema.json',
    input: [],
  },
}

Установите output: [], если никакие файлы не должны восстанавливаться при попадании в кэш.

Кооперативное отслеживание

Отслеживание файловой системы фиксирует обращения к файлам. Оно не может определить, зачем инструмент использовал каждый из путей.

vp build знает о сборке Vite больше, чем Vite Task может определить только по обращениям к файлам. Когда vp build выполняется с включённым кэшированием, Vite передаёт эти метаданные в Vite Task. Vite Task объединяет этот отчёт с данными отслеживания файловой системы, чтобы создать более точный отпечаток кэша.

Для стандартной сборки Vite вам не нужно добавлять эти записи вручную, поскольку Vite автоматически передаёт их во время выполнения:

• env: ['VITE_*'] или env: ['NODE_ENV']
• output: ['dist/**']
• исключения входных или выходных данных для временных путей, таких как node_modules/.vite-temp

Вам нужно только определить задачу с помощью vp build:

vite.config.ts

import { defineConfig } from 'vite-plus';

export default defineConfig({
  run: {
    tasks: {
      frontendBuild: 'vp build',
    },
  },
});

Запустите эту задачу с помощью vpr frontendBuild или vp run frontendBuild.

Ручная настройка переопределяет переданные метаданные. Добавляйте input, output, env или untrackedEnv, если в вашем проекте есть поведение, которое Vite не может автоматически определить.

В настоящее время Vite+ поддерживает кооперативное отслеживание для vp build. В будущем эта поддержка будет расширена и на другие официальные инструменты. Сторонние инструменты могут передавать метаданные кэша с помощью @voidzero-dev/vite-task-client.

Когда добавлять ручную настройку

Добавляйте настройку, когда в проекте есть поведение, о котором команда или инструмент не могут узнать автоматически.

Случай	Пример
Исключить каталог выходных данных из входных данных	input: [{ auto: true }, '!dist/**']
Исключить временный сгенерированный файл из отслеживания входных и выходных данных	input: [{ auto: true }, '!.tmp/config.mjs'] output: [{ auto: true }, '!.tmp/config.mjs']
Избежать автоматического отслеживания файлов для задачи	input: ['src/**'] output: ['dist/**']
Отслеживать и передавать переменную окружения	env: ['NODE_ENV']
Передавать переменную окружения без добавления в отпечаток кэша	untrackedEnv: ['GITHUB_ACTIONS']