#Как проявляется ошибка и когда применим способ
В package.json версии допускают диапазоны ^ и ~, а npm выбирает конкретную версию по lock-файлу или, при его отсутствии, из доступных подходящих выпусков. Если ожидали одну версию, а получили другую, сначала проверьте, что говорит локальный package-lock.json.
#Причины и признаки
| Возможная причина | Как узнать | Что делать |
|---|---|---|
| Широкий диапазонЗнак ^ обычно разрешает совместимые изменения внутри диапазона SemVer, а ~ — более узкие исправления. | Пакет имеет более новую фактическую версию, чем записанный минимум. | Уточнить желаемый диапазон и обновить lock. |
| Старый lockДаже после изменения package.json согласованный lock может удерживать старую допустимую версию. | npm ls и package-lock.json показывают одну и ту же зафиксированную версию. | Изменять lock контролируемым обновлением. |
#Пошаговая диагностика и решение
- 1. Определите точный установленный пакетОткройте терминал в корне проекта и подставьте в команду настоящее имя пакета вместо ИМЯ_ПАКЕТА. Сравните версию зависимости на верхнем уровне дерева и версию, которая ожидалась; при вложенной зависимости смотрите дерево целиком.
- Замените ИМЯ_ПАКЕТАLinux · Терминал (Bash)КомандаЗамените ИМЯ_ПАКЕТА. Команда только показывает дерево установленных версий.
npm ls ИМЯ_ПАКЕТА
- 2. Посмотрите правило в package.jsonВ редакторе откройте package.json и найдите имя пакета в dependencies или devDependencies. Различайте запись 1.2.3, ^1.2.3, ~1.2.3 и диапазон >=; звездочка позволяет особенно широкий выбор. Запишите желаемую и допустимую версии до любых правок.
- 3. Сравните версию в lock-файлеОткройте package-lock.json в редакторе и найдите packages["node_modules/ИМЯ_ПАКЕТА"], если это простой пакет верхнего уровня. Для вложенной зависимости путь может быть другим. Запишите поле version; не меняйте его текстовым редактором, иначе нарушится согласованность контрольных сумм.
- 4. Проверьте доступные выпуски и требованияИз папки проекта выполните npm view с реальным именем пакета. Сопоставьте список релизов и требование engines (если опубликовано). При работе с приватным реестром версии могут отличаться от публичного npm; не подменяйте источник пакета без разрешения.
- Только чтение метаданных настроенного реестра; замените имя пакетаLinux · Терминал (Bash)КомандаТолько чтение метаданных настроенного реестра; замените имя пакета.
npm view ИМЯ_ПАКЕТА versions --jsonnpm view ИМЯ_ПАКЕТА engines --json
- 5. Поменяйте правило версии в копииСделайте Git-ветку и уточните значение нужного пакета в package.json. Если нужен строго определённый выпуск, используйте точную проверенную версию, без ^ и ~; затем выполните npm install в копии. Просмотрите изменения package-lock.json. Не фиксируйте наугад версии у всех пакетов.
- 6. Проведите воспроизводимую установкуВ тестовой копии выполните npm ci и затем npm ls для нужного пакета. Убедитесь, что итоговая версия соответствует ожидаемой, выполните тесты проекта. Если она не подходит зависимостям второго уровня, рассмотрите вывод npm explain, не применяйте --force.
- Дополнительная команда по темеLinux · Терминал (Bash)С осторожностьюnpm ci заменяет node_modules текущей копии; npm explain показывает причину включения пакета.
npm cinpm explain ИМЯ_ПАКЕТАКоманда может изменить состояние системы или её настройки. Проверьте параметры и последствия перед запуском.
#Проверка результата и действия при повторении
После согласования диапазона, lock-файла и фактической установки npm ls должен показывать целевой выпуск. При повторном npm ci версия не должна меняться. При ошибке загрузки смотрите реестр и версию Node.js отдельно.
Если на указанном шаге результат отличается, остановитесь и запишите первое полное сообщение об ошибке, версию инструментов и проверенное состояние до исправления. Не переходите к опасным действиям на действующем проекте: повторите проверку на отдельной копии, верните сохранённые файлы и только затем выбирайте следующую причину.