npm --prefer-offline и --offline: что выбрать

Что делает --prefer-offline по документации npm

Официальная конфигурация npm описывает `prefer-offline` так: проверки устаревания кэшированных данных обходятся, но отсутствующие данные всё равно запрашиваются с сервера. То есть флаг не гарантирует установку без интернета. Если нужный tarball и метаданные уже есть в локальном кэше, npm будет склонен использовать их без лишней проверки свежести. Если чего-то не хватает, клиент может обратиться к настроенному registry и скачать недостающее. Такой режим полезен при медленной или нестабильной сети, когда хочется снизить количество запросов, но сохранить возможность восстановить недостающие зависимости.

Важно: Если цель — доказать, что сборка действительно автономна, `--prefer-offline` не подходит как тест: он способен незаметно добрать недостающий пакет.

Что меняется в настоящем --offline

`--offline` строже: npm не выполняет сетевые запросы. Любая зависимость, метаданные или архив, которых нет в локальном кэше, превращаются в ошибку вместо обращения к registry. Поэтому этот флаг полезен в полностью изолированной среде и как проверка того, что локальный набор данных действительно достаточен. Он не означает «используй кэш чуть сильнее» — он меняет допустимый источник на полностью локальный. Если установка с prefer-offline проходит, а с offline падает, это прямой сигнал, что первая команда всё ещё пользовалась сетью или нуждалась в данных, отсутствующих локально.

Сравнение npm --prefer-offline и --offline

• Сетевые запросы. Разрешены при отсутствии данных. Запрещены полностью
• Проверка свежести кэша. Пропускается для кэшированных данных. Сеть не используется вообще
• Нет нужного tarball. npm может скачать его. Команда завершается ошибкой
• Проверка автономности. Не подходит как доказательство. Подходит
• Медленная сеть. Полезен как компромисс. Только при полном кэше

Предупреждение: Локальный npm cache — не замена корпоративному артефактному хранилищу. Для надёжного CI важнее lockfile и контролируемый registry или proxy.

Как выбрать режим под конкретную задачу

1. Если сеть доступна, но вы хотите сократить лишние проверки registry, используйте `npm install --prefer-offline` или эквивалентную команду.
2. Если сеть запрещена политикой или вы хотите проверить автономность сборки, используйте `npm install --offline`.
3. Перед offline-проверкой выполните обычную установку в контролируемой среде, чтобы нужные артефакты могли попасть в кэш.
4. Зафиксируйте `package-lock.json` и убедитесь, что он соответствует `package.json`; это уменьшает неопределённость версий.
5. Если offline падает, выясните, какого пакета или метаданных не хватает. Не начинайте с удаления кэша.
6. Для стабильного CI используйте общий cache proxy или внутренний registry, а не случайно прогретый кэш одного runner.

Совет: Повторите проблемную команду без `--offline`: если npm сразу начинает скачивание, причина почти наверняка в неполном локальном наборе данных.

Почему prefer-online не является просто «обратным offline»

У npm есть ещё `prefer-online`: этот режим заставляет проверять свежесть данных через сеть даже тогда, когда кэш уже содержит запись. Он не выключает кэш и не означает «скачать всё заново». Три режима лучше понимать как политики доступа: prefer-online усиливает свежесть, prefer-offline доверяет имеющемуся кэшу и обращается в сеть только при необходимости, offline запрещает сеть полностью. Такая модель помогает диагностировать странное поведение: если проблема исчезает только с prefer-online, возможно, мешали устаревшие метаданные; если проявляется только offline, локальному кэшу чего-то не хватает.

Почему прогретый кэш не гарантирует воспроизводимую установку

Даже если проект уже устанавливался на машине, это не означает, что любой будущий `npm install --offline` сработает. Мог измениться lockfile, registry, платформа, версия Node.js или набор optional dependencies. Некоторые install-скрипты сами обращаются в интернет и не подчиняются семантике npm cache так, как обычная загрузка tarball. Поэтому автономность проверяют отдельно: чистый рабочий каталог, ожидаемый lockfile, отключённая сеть или `--offline`, и контроль того, что lifecycle-скрипты не тянут внешние бинарники. В CI такой тест полезно выполнять заранее, а не в день, когда сеть уже недоступна.

Как работать с кэшем без вредных ритуалов

Ошибка offline не означает, что кэш «сломался». Часто там просто нет нужного артефакта. Команды вроде `npm cache verify` помогают проверить структуру кэша, но слепая очистка `npm cache clean --force` уничтожает локальные данные и делает автономную установку ещё менее вероятной. Если подозреваете повреждение, сначала прочитайте сообщение npm, определите конкретную зависимость и сравните поведение online/offline. Для повторяемых сборок лучше использовать предсказуемую систему кеширования CI или прокси-репозиторий, где можно контролировать retention и доступ к версиям.

Как отличить ускорение установки от гарантии автономности

В практической работе эти флаги стоит применять с разными критериями успеха. Для `--prefer-offline` хороший результат — меньше сетевых обращений при сохранённой способности скачать отсутствующую зависимость. Для `--offline` успех означает, что установка завершилась вообще без registry и других сетевых запросов со стороны самого npm. Поэтому тесты тоже различаются: prefer-offline сравнивают по скорости и количеству запросов, а offline запускают в изолированной среде и заранее проверяют, что нужные артефакты доступны локально. Не смешивайте эти цели в одном CI job: иначе зелёная сборка с prefer-offline может создать ложное ощущение полной автономности.

Перед использованием --offline в CI или закрытом контуре

• package-lock.json закоммичен и соответствует package.json.
• Требуемые версии ранее были доступны из ожидаемого registry.
• Offline проверен отдельно, а не заменён prefer-offline.
• Scoped registry и основной registry не меняются между подготовкой и запуском.
• Lifecycle-скрипты не требуют внешней сети или это учтено отдельно.
• Ошибка cache miss анализируется до любых команд очистки кэша.

Совет: Не очищайте npm cache перед автономной сборкой «для чистоты». Вы удалите именно те данные, на которые рассчитывает offline.

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

У npm есть ещё `prefer-online`: этот режим заставляет проверять свежесть данных через сеть даже тогда, когда кэш уже содержит запись. Он не выключает кэш и не означает «скачать всё заново». Три режима лучше понимать как политики доступа: prefer-online усиливает свежесть, prefer-offline доверяет имеющемуся кэшу и обращается в сеть только при необходимости, offline запрещает сеть полностью. Такая модель помогает диагностировать странное поведение: если проблема исчезает только с prefer-online…

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

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

• Config | npm Docs