Почему npm install падает — 4 причины и как починить

npm install, ждёшь, и вместо зелёного — простыня красных npm ERR!. Знакомо и бесит. Но хорошая новость: почти все провалы npm install — это одна из четырёх причин, и чинятся они парой команд, а не переустановкой всего на свете. Разберём их по порядку — от самой частой к редкой, — чтобы ты знал, что жать.

Сначала прочитай ошибку — там половина ответа

Прежде чем гуглить, прочитай первые красные строки. npm почти всегда пишет, что именно не так: ERESOLVE, EACCES, ENOTFOUND, «Unsupported engine». Эти коды — прямая подсказка на причину ниже. Скопировать ошибку целиком и скормить ИИ — тоже рабочий ход; как это делать с толком, в гайде как чинить баги вместе с ИИ.

Теперь по причинам.

Причина 1. Не та версия Node (самая частая)

Проект часто требует конкретную версию Node — библиотека собиралась под неё. У тебя стоит другая → сборка падает, иногда с мутной ошибкой про engine или про непонятный модуль.

Как проверить: node -v покажет твою версию. Загляни в package.json проекта: если там есть блок "engines": { "node": ">=20" }, а у тебя 18 — вот и причина. README проекта тоже часто называет нужную версию.

Как починить: поставь нужную версию Node. Проще всего через менеджер версий (nvm): nvm install 20 && nvm use 20. Он держит несколько версий рядом и переключает под проект — маст-хэв, если проектов больше одного.

Причина 2. Битый кэш или node_modules

Иногда установка на середине сорвалась (сеть моргнула, нажал Ctrl+C), и папка node_modules осталась в полусобранном виде. Дальше любой install спотыкается о свой же мусор.

Как проверить: ошибка выглядит хаотично — то один модуль, то другой, при повторе меняется. Верный признак «грязного» состояния.

Как починить — три команды, снести и собрать заново начисто:

1. rm -rf node_modules — удалить полусобранную папку (в Windows — rmdir /s /q node_modules).
2. npm cache clean --force — очистить кэш npm.
3. npm install — поставить с нуля.

Это лечит удивительно много случаев. Если после «магических» ошибок сомневаешься — начни отсюда.

Причина 3. Конфликт зависимостей (ERESOLVE)

Ошибка ERESOLVE unable to resolve dependency tree. По-русски: две библиотеки хотят разные несовместимые версии третьей, и npm не знает, кого слушать.

Как проверить: в ошибке npm прямо пишет, кто с кем не сошёлся — «пакет A хочет B версии 2, а пакет C — версии 3».

Как починить:

• Первым делом обнови конфликтующие пакеты до свежих версий (npm install пакет@latest) — часто в новых конфликт уже устранён.
• Если горит и надо сейчас — npm install --legacy-peer-deps. Это говорит npm «не будь так строг к peer-зависимостям». Рабочий костыль, но именно костыль: он глушит предупреждение, а не решает несовместимость, так что потом стоит вернуться и разобраться.
• Не хватай --force вслепую — он ставит заведомо конфликтующее и может собрать нерабочее.

Причина 4. Сеть, прокси, права

Реже, но бывает. ENOTFOUND или таймаут — npm не достучался до реестра (нет сети, VPN/прокси, лежит зеркало). EACCES — не хватает прав на запись.

Как проверить и починить:

• ENOTFOUND/таймаут: проверь интернет, выключи VPN/прокси, повтори. Если сеть корпоративная — возможно, нужен свой реестр.
• EACCES: не решай это через sudo npm install — это частый плохой совет, он портит права ещё сильнее. Правильнее — починить владельца папки npm или использовать nvm, который ставит всё в твою домашнюю папку без прав администратора.

Если хочется понять, что вообще делает npm и откуда берутся все эти пакеты — это работа менеджера пакетов, общая картина там.

Что за package-lock.json и надо ли его трогать?

package-lock.json фиксирует точные версии всего, что установилось, чтобы у тебя и у другого собралось одинаково. Руками его не редактируй. Но если зависимости совсем запутались, помогает снести node_modules и package-lock.json, потом npm install — npm пересоберёт лок начисто. Только не удаляй package.json — вот его трогать нельзя, это список твоих зависимостей.

Стоит ли перейти на pnpm?

Если npm часто мучает — да, стоит попробовать. pnpm ставит те же пакеты, но быстрее и экономнее по диску, а с конфликтами ведёт себя строже и понятнее. Команды почти те же (pnpm install). Многие проекты сидят на pnpm именно из-за меньшей боли с зависимостями.