Vite+

Кэш GitHub Actions ​

Экспериментальная функция

Повторное использование кэша Vite Task между запусками GitHub Actions является экспериментальной возможностью. Протестируйте её и оцените результаты в своём проекте перед использованием в CI.

Vite Task сохраняет результаты выполнения задач в node_modules/.vite/task-cache в корне рабочего пространства. Восстанавливайте этот каталог при последующих запусках GitHub Actions, чтобы Vite Task мог повторно использовать результаты предыдущих задач.

Кэш GitHub Actions и Vite Task принимают решения независимо друг от друга:

  1. actions/cache восстанавливает и сохраняет каталог кэша на основе ключа из вашего workflow.
  2. Vite Task использует восстановленный каталог кэша и повторно выполняет только те задачи, чьи отпечатки всё ещё совпадают.

Перед началом ​

Используйте этот workflow, если выполняются все следующие условия:

  • Команда запускается через vp run.
  • При непосредственном повторном запуске задача сообщает о попадании в кэш.
  • Задача имеет стабильное отслеживание входных и выходных данных для CI.
  • Workflow устанавливает зависимости до восстановления node_modules/.vite/task-cache.

Если непосредственный повторный запуск не использует кэш, исправьте конфигурацию отслеживания задачи перед добавлением кэша GitHub Actions. Возможные причины нестабильного кэширования и способы их устранения см. в разделе Когда добавлять ручную настройку.

Оцените необходимость кэширования между запусками ​

Вам может не потребоваться восстановление кэша Vite Task между запусками GitHub Actions, если:

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

Оцените результаты перед добавлением кэша GitHub Actions для Vite Task. Сравните длительность workflow с шагами восстановления и сохранения кэша и без них. Проверьте как время выполнения шага кэша GitHub, так и время выполнения vp run.

1. Определите задачи CI, поддерживающие кэширование ​

Только команды, запущенные через vp run, используют кэширование Vite Task. Прямая команда, например vp build, не использует кэш задач. Определите задачу в vite.config.ts для каждой команды, результаты которой вы хотите кэшировать в CI:

vite.config.ts
ts
import { defineConfig } from 'vite-plus';

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

Это руководство предполагает, что каждая задача уже использует кэш локально. Если задача не попадает в кэш, исправьте её конфигурацию отслеживания в vite.config.ts перед добавлением шагов кэша GitHub Actions. См. разделы Автоматическое отслеживание данных и run.tasks.

Запустите каждую задачу дважды:

bash
vp run build
vp run build # должно вывести "cache hit"
vp run lint
vp run lint # должно вывести "cache hit"

2. Восстановите кэш после установки зависимостей ​

Восстанавливайте node_modules/.vite/task-cache после выполнения vp install, поскольку установка пакетов может создавать или изменять содержимое node_modules.

.github/workflows/ci.yml
yaml
name: CI

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: voidzero-dev/setup-vp@v1
        with:
          node-version: '24'
          cache: true

      - run: vp install

      - name: Restore Vite Task cache
        id: vite-task-cache
        uses: actions/cache/restore@v6
        with:
          path: node_modules/.vite/task-cache
          key: vite-task-${{ runner.os }}-${{ runner.arch }}-${{ github.run_id }}-${{ github.run_attempt }}
          restore-keys: |
            vite-task-${{ runner.os }}-${{ runner.arch }}-

      - run: vp run lint
      - run: vp run build

      - name: Save Vite Task cache
        if: success()
        uses: actions/cache/save@v6
        with:
          path: node_modules/.vite/task-cache
          key: ${{ steps.vite-task-cache.outputs.cache-primary-key }}

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

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

Для монорепозиториев восстанавливайте кэш задач из корня рабочего пространства. Затем запускайте те же команды vp run, которые используются локально, например vp run -t @my/app#build. Vite Task сможет повторно использовать результаты для запрошенного пакета и пакетов, от которых он зависит.

3. Проверьте логи ​

При первом запуске шаг восстановления должен сообщить, что кэш не найден, а шаг сохранения должен создать новую запись. Pull request'ы из форков могут работать только в режиме восстановления, поскольку GitHub может предоставить токен кэша только с правами на чтение. В этом случае шаг сохранения выдаст предупреждение и успешно завершится без создания записи кэша.

При последующем запуске проверьте оба уровня:

text
Cache restored from key: vite-task-Linux-X64-...
$ vp build ◉ cache hit, replaying
vp run: cache hit, 1.10s saved.

Если GitHub восстанавливает кэш, но Vite Task сообщает о промахе кэша, это означает, что workflow восстановил каталог кэша, но отпечаток задачи изменился.

Сохраняйте стабильность отслеживания задач ​

Если GitHub восстанавливает кэш, но vp run сообщает о промахе кэша, исправьте отпечаток задачи перед изменением ключа кэша Actions. См. разделы Автоматическое отслеживание данных и run.tasks.

Выберите ключ кэша ​

Используйте изменяемый основной ключ и префикс восстановления:

.github/workflows/ci.yml
yaml
key: vite-task-${{ runner.os }}-${{ runner.arch }}-${{ github.run_id }}-${{ github.run_attempt }}
restore-keys: |
  vite-task-${{ runner.os }}-${{ runner.arch }}-

Основной ключ уникален для каждого запуска, поскольку содержит github.run_id и github.run_attempt. После этого GitHub ищет кэш по префиксу восстановления и восстанавливает самый новый подходящий кэш.

Включайте:

  • runner.os и runner.arch, поскольку выходные данные и нативные инструменты могут зависеть от платформы.
  • Значение, уникальное для запуска, например github.run_id и github.run_attempt, поскольку записи кэша GitHub являются неизменяемыми.

Если файл зависимости влияет на результат выполнения задачи, отслеживайте его в отпечатке задачи, а не в ключе GitHub Actions.

Управление очисткой и областью действия кэша ​

GitHub удаляет кэши в соответствии с правилами хранения кэшей и ограничениями хранилища репозитория. Область действия кэша также зависит от ветки: запуски workflow могут восстанавливать кэши из текущей ветки и ветки по умолчанию, тогда как кэши для merge-ref pull request'ов имеют ограниченную область действия.

Vite Task может очистить весь кэш задач, но в настоящее время не выполняет удаление отдельных записей задач по возрасту или размеру. По мере сохранения новых записей задач и архивов выходных файлов каталог node_modules/.vite/task-cache может продолжать увеличиваться.

Управляйте размером на уровне кэша GitHub Actions:

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

Актуальные правила очистки и области действия см. в разделе Справочник по кэшированию зависимостей GitHub.

© 2026 VoidZero Inc. и контрибьюторы Vite+.