#Как проявляется ошибка и когда применим способ
Подозрение на повреждённый кеш npm возникает при ошибках целостности загруженного архива либо повторном неуспехе установки из локального кеша. У современных версий npm содержимое кеша обычно проверяется по контрольным суммам; сначала используйте встроенную проверку.
#Причины и признаки
| Возможная причина | Как узнать | Что делать |
|---|---|---|
| Повреждена локальная записьСетевое скачивание прерывалось, а кеш содержит неполные или некорректные данные. | Лог содержит integrity/кеш-ошибку и повторяется с одним пакетом. | Проверить и обслужить кеш. |
| Ошибка не в кешеПроблема обусловлена доступом к registry, сертификатом, нехваткой места или зависимостями. | npm cache verify завершается успешно, но установка всё равно не работает. | Диагностировать исходную ошибку без очистки кеша. |
#Пошаговая диагностика и решение
- 1. Запишите исходную неисправностьВ терминале проекта сохраните первое сообщение ошибки и имя пакета. Проверьте, что диск не переполнен и доступен настроенный registry. Если лог сообщает ERESOLVE, 404 или проблемы сертификата, очистка кеша обычно не устраняет причину; переходите к соответствующей диагностике.
- 2. Узнайте реальный путь храненияВ Linux, Windows PowerShell или macOS выполните npm config get cache от обычного пользователя. Сохраните полученный путь для сравнения после проверки. Не удаляйте его Проводником и не переносите вместе с действующими файлами проекта.
- Чтение пути кеша текущего профиля; не требует прав администратораLinux · Терминал (Bash)КомандаЧтение пути кеша текущего профиля; не требует прав администратора.
npm config get cache
- 3. Запустите встроенную проверкуВ той же оболочке выполните npm cache verify. Дождитесь завершения: команда проверяет содержимое, удаляет ненужные записи и сообщает результаты. Если выдаёт EACCES, сначала устраните права доступа к конкретному каталогу, а не запускайте проверку через sudo.
- Безопасная процедура проверки содержимого кеша; может удалять только ненужные кеш-записиLinux · Терминал (Bash)КомандаБезопасная процедура проверки содержимого кеша; может удалять только ненужные кеш-записи.
npm cache verify
- 4. Проверьте конкретную записьДля поиска пакета выполните npm cache ls ИМЯ_ПАКЕТА, заменив его на настоящее имя. Вывод может показать адреса и версии, но наличие записи не доказывает, что сервер доступен. Команда полезна, чтобы отличить кэшированный пакет от неисправности сети.
- Только чтение списка записей по конкретному пакетуLinux · Терминал (Bash)КомандаТолько чтение списка записей по конкретному пакету.
npm cache ls ИМЯ_ПАКЕТА
- 5. Повторите установку на копииПодготовьте тестовую копию с неизменёнными package.json и lock-файлом, а затем выполните npm ci. Если ранее повреждённые данные перепроверились и пакет загрузился, проблема решена. Если появился 404 или CERT_HAS_EXPIRED, проверьте реестр/сертификаты отдельно.
- В тестовой копии: заменяет node_modules; установочные скрипты исполняютсяLinux · Терминал (Bash)С осторожностьюВ тестовой копии: заменяет node_modules; установочные скрипты исполняются.
npm ciКоманда может изменить состояние системы или её настройки. Проверьте параметры и последствия перед запуском.
- 6. Не очищайте весь кеш без необходимостиКоманда npm cache clean --force удаляет содержимое кеша и не является стандартным первым шагом; она ухудшит автономную установку и вызовет повторное скачивание. Используйте её только при подтверждённой неисправности, согласованном резервном плане и возможности повторно загрузить пакеты.
- 7. Зафиксируйте проверку и следующий шагСохраните первое сообщение ошибки, вывод npm cache verify и итог npm ci. Если результат не изменился, восстановите тестовую копию и переходите к диагностике источника пакетов, разрешений или версии Node.js. Изменять системные папки ради кеша нельзя.
#Проверка результата и действия при повторении
Проверка npm cache verify завершена без ошибок, а установка в тестовой папке проходит с прежним lock-файлом. Повторный npm ci подтверждает, что случайное сетевое прерывание не маскирует проблему.
Если на указанном шаге результат отличается, остановитесь и запишите первое полное сообщение об ошибке, версию инструментов и проверенное состояние до исправления. Не переходите к опасным действиям на действующем проекте: повторите проверку на отдельной копии, верните сохранённые файлы и только затем выбирайте следующую причину.