yarn install --immutable: зачем нужен в CI

Что именно запрещает флаг --immutable

`--immutable` не означает «Yarn вообще ничего не пишет на диск». Он относится к набору файлов, которые объявлены неизменяемыми, прежде всего к lockfile. Если manifests требуют разрешения, которое не соответствует текущему `yarn.lock`, Yarn не должен тихо сгенерировать новый граф в CI: вместо этого он завершает команду ненулевым кодом. Это полезно, потому что разработчик видит проблему до сборки артефакта. В документации также упоминается `immutablePatterns`, позволяющий добавить другие пути к такой проверке. Старое имя `--frozen-lockfile` сохранено как alias ради совместимости, но Yarn предупреждает о его будущем удалении.

Совет: Для новых CI-конфигураций используйте `--immutable`, а не строите долгоживущую конфигурацию вокруг устаревающего alias `--frozen-lockfile`.

Как настроить воспроизводимую установку в CI

1. Зафиксируйте версию Yarn: Используйте `packageManager`/Corepack или другой контролируемый механизм, чтобы локальная и CI-версия не расходились.
2. Коммитьте manifest и lockfile вместе: Изменение `package.json` без соответствующего `yarn.lock` должно считаться неполным pull request.
3. Запускайте `yarn install --immutable`: Пусть job падает, если разрешение зависимостей требует правки lockfile.
4. Для Zero-Installs добавьте контроль cache: Yarn приводит пример `--immutable --immutable-cache`; для внешних PR рекомендует дополнительно `--check-cache`.
5. Не переписывайте lockfile внутри CI: Исправляйте проблему локально, проверяйте diff и коммитьте результат отдельным изменением.
6. После install запускайте тесты: Immutable гарантирует согласованность зависимостей, но не функциональную корректность приложения.

Важно: Если CI автоматически коммитит изменённый lockfile, смысл immutable-проверки теряется: review уже не контролирует исходный граф зависимостей.

--immutable, --immutable-cache и --check-cache

• --immutable. Lockfile и другие immutablePatterns. Обычный CI для защиты от незакоммиченного изменения разрешений
• --immutable-cache. Запрещает добавлять или удалять файлы в cache folder. Zero-Installs, где cache хранится в репозитории
• --check-cache. Повторно скачивает пакеты и сверяет checksum с lockfile/cache. Более строгая проверка Zero-Installs, особенно при внешних PR
• --refresh-lockfile. Обновляет metadata при сохранении resolutions. Отдельная проверка metadata; в сочетании с immutable может валидировать согласованность

Почему локально install проходит, а CI падает

Первая причина — локально использовалась другая версия Yarn. Вторая — разработчик изменил manifest, Yarn обновил lockfile, но файл не попал в commit. Третья — ветка после merge/rebase получила конфликт или старую версию `yarn.lock`. В Zero-Installs добавляются расхождения cache: локально пакет уже есть, а репозиторий не содержит ожидаемый cache artifact. Наконец, различия конфигурации `.yarnrc.yml` могут менять resolver или linker. Правильная реакция — воспроизвести CI той же версией Yarn и сравнить исходные файлы, а не отключить immutable ради зелёного статуса.

Предупреждение: `--immutable=false` как постоянный обход CI-ошибки маскирует рассинхронизацию и делает dependency graph зависимым от момента запуска.

Как чинить ошибку без ручного редактирования yarn.lock

Переключитесь на ту же ветку и версию Yarn, что использует pipeline, затем выполните обычный `yarn install` локально в контролируемой среде. Просмотрите diff: он должен объясняться изменениями manifests или merge. Если lockfile меняется без ожидаемой причины, сначала проверьте версию package manager и конфигурацию. После осмысленного обновления запустите `yarn install --immutable` повторно: теперь он должен пройти без диффа. Ручное редактирование больших блоков `yarn.lock` опасно, потому что формат отражает resolution и checksums; генерировать его должен сам package manager. При конфликте лучше восстановить manifests и дать Yarn построить согласованное состояние.

CI-проверка, которая действительно даёт пользу

• Версия Yarn одинакова на ноутбуках и в CI.
• `package.json` и `yarn.lock` меняются в одном pull request.
• Install job использует `--immutable` или полагается на подтверждённый CI default осознанно.
• Zero-Installs repository при необходимости проверяет immutable cache.
• Внешние pull request не могут незаметно подменить cached package без checksum-проверки.
• CI не запускает авто-commit lockfile после проверки.
• После dependency install выполняются тесты, typecheck и сборка.

Важно: Immutable защищает воспроизводимость разрешения зависимостей, но не является security scanner и не гарантирует отсутствие уязвимостей в выбранных версиях.

Когда достаточно --immutable, а когда нужна более строгая схема

Для обычного проекта, где cache не хранится в Git, основной контроль — согласованный `yarn.lock`, поэтому `--immutable` закрывает ключевой сценарий. В Zero-Installs команда может работать без обычного fetch после clone, и тогда содержимое cache становится частью доверяемого состояния; Yarn предлагает `--immutable-cache`, а при внешних PR — более строгий `--check-cache`, который перепроверяет checksums через повторную загрузку. Степень строгости должна соответствовать модели репозитория. Не нужно механически включать каждый флаг: важно понимать, какой файл или кэш вы защищаете и кто имеет возможность его изменить.

Что проверять после merge двух веток с зависимостями

Конфликт `yarn.lock` после merge не стоит разрешать выбором «ours» или «theirs» вслепую. Сначала объедините изменения manifest-файлов, затем той же версией Yarn восстановите согласованный lockfile и внимательно просмотрите diff. После этого `yarn install --immutable` должен пройти без записи новых изменений. Такой порядок особенно важен, когда две ветки независимо обновляли близкие транзитивные зависимости. Если immutable падает уже после корректного merge, сравните `.yarnrc.yml`, версию Yarn и файлы cache, прежде чем подозревать сам пакет.

Что учитывать

Первая причина — локально использовалась другая версия Yarn. Вторая — разработчик изменил manifest, Yarn обновил lockfile, но файл не попал в commit. Третья — ветка после merge/rebase получила конфликт или старую версию `yarn.lock`. В Zero-Installs добавляются расхождения cache: локально пакет уже есть, а репозиторий не содержит ожидаемый cache artifact. Наконец, различия конфигурации `.yarnrc.yml` могут менять resolver или linker. Правильная реакция — воспроизвести CI той же версией Yarn и…

Источники и проверка

Фактическая часть сверена по первичным источникам (в т.ч. yarn install). Пример и формулировки — редакция N1RO на 2026-09-20.

• yarn install