В macOS сначала определите, сообщает ли npm о конфликте слияния Git, несоответствии между package.json и package-lock.json или об ошибке разрешения peer-зависимостей. Перед внесением каких-либо изменений проверьте файлы проекта, состояние Git и версии npm в Терминале. Если согласовать нужно только lockfile, параметр npm --package-lock-only может обновить его без переустановки пакетов в node_modules.

Начните с папки проекта и сохраните текущее состояние

Откройте Терминал, перейдите в каталог проекта и убедитесь, что вы находитесь в нужном корневом каталоге проекта. В Finder можно найти папку, а затем использовать команду Терминала cd; если путь содержит пробелы, заключите его в кавычки, например cd "$HOME/Projects/My App". Выполните:

pwd
git status --short
node --version
npm --version

Команда git status --short показывает, есть ли в каком-либо из манифестов незафиксированные изменения. Если есть изменения, которые необходимо сохранить, сохраните или закоммитьте их перед продолжением; не перезаписывайте файлы, пока вы еще решаете, какие изменения зависимостей должны остаться. Зафиксируйте версии Node.js и npm, чтобы вы могли сравнить их с задокументированной настройкой проекта или конфигурацией непрерывной интеграции (CI). Форматы lockfile npm менялись в разных мажорных версиях npm, поэтому разница в форматах может объяснять неожиданные массовые изменения без фактической поломки самих зависимостей. Документация npm по package-lock

Определите тип возникшего конфликта

Если package-lock.json содержит маркеры Git, такие как <<<<<<<, ======= или >>>>>>>, это конфликт слияния системы контроля версий. Изучите затронутые разделы полностью и сравните изменения в обеих ветках. Сначала разрешите объявления зависимостей в package.json: старые руководства npm по разрешению конфликтов в lockfile явно рекомендуют вручную разрешать конфликты манифестов перед повторной генерацией lockfile. Не оставляйте одну из версий lockfile просто по привычке; каждая ветка могла добавить или изменить зависимости. Руководство npm по конфликтам package-lock

Если маркеров Git нет, сравните имена и диапазоны версий зависимостей в package.json с lockfile. package.json указывает допустимые диапазоны, тогда как lockfile фиксирует разрешенное дерево зависимостей. Согласно текущей документации npm, обычная команда npm install использует зафиксированные версии, если они удовлетворяют диапазонам манифеста, и обновляет lockfile, если это не так. Как npm install использует lockfile

Если команда завершается ошибкой с сообщением о peer-зависимости, сосредоточьтесь на указанных в этой ошибке пакетах и их peer-требованиях. Это может быть реальная несовместимость между объявленными диапазонами пакетов, а не поврежденная установка. Не используйте --force или --legacy-peer-deps в качестве быстрого способа диагностики: изменение поведения разрешения зависимостей может привести к созданию дерева, отличного от предполагаемой структуры проекта.

Изучите изменения перед тем, как запускать согласование в npm

Просмотрите историю проекта и текущий diff:

git diff -- package.json package-lock.json
git log -5 --oneline -- package.json package-lock.json

Найдите коммит или ветку, которые изменили объявление зависимости, версию lockfile или конфигурацию npm. Также проверьте, есть ли в проекте файл .npmrc; в документации npm указано, что параметры, формирующие структуру дерева, такие как legacy-peer-deps или install-links, могут влиять на то, будут ли согласовываться lockfile и последующая чистая установка. Используйте те же специфичные для проекта настройки, которые уже приняты в репозитории, вместо добавления случайных флагов. Документация по npm ci

Значение lockfileVersion помогает определить формат файла, но не стоит считать его исчерпывающим диагнозом само по себе. В документации npm описаны версии формата 1, 2 и 3, и отмечается, что более новые версии npm могут обновлять более старые lockfile. Изменение версии может отражать поведение совместимости npm; изучите фактический diff зависимостей, прежде чем принимать масштабную перезапись файла. Формат lockfile и более старые файлы

Согласуйте lockfile без переустановки зависимостей

После устранения маркеров конфликта и приведения package.json в корректное состояние дайте npm команду обновить только lockfile:

npm install --package-lock-only

В документации npm указано, что эта опция обновляет package-lock.json без проверки node_modules и без загрузки зависимостей. Это точечный шаг согласования; он не гарантирует, что полученный набор зависимостей в точности соответствует запланированному вами, поэтому после этого обязательно изучите diff. Параметры npm install

git diff --check
git diff -- package.json package-lock.json
git status --short

git diff --check помогает выявить ошибки, связанные с пробелами, а сам diff показывает, что именно изменил npm. Убедитесь, что в манифест не попали непреднамеренные правки, проверьте непредвиденные изменения версий или масштабную перезапись lockfile и удостоверьтесь, что маркеры конфликтов удалены. Если предложенные изменения кажутся нелогичными, восстановите файлы из сохраненного состояния или системы контроля версий и заново проанализируйте причину вместо того, чтобы удалять node_modules или генерировать все с нуля.

Знайте, когда уместна чистая установка

Используйте npm ci только после того, как манифест и lockfile будут намеренно согласованы и вам потребуется воспроизвести зафиксированное дерево зависимостей. Эта команда требует наличия lockfile, завершается ошибкой вместо обновления при несовпадении и удаляет существующий каталог node_modules перед установкой. Это делает ее полезной для подтверждения разрешенного состояния, однако она не является безопасной командой для простой инспекции. Поведение npm ci

Если npm install --package-lock-only не может разрешить конфликт, зафиксируйте точный текст ошибки, просмотрите указанные диапазоны пакетов и настройки npm в проекте, а затем сравните их с веткой или окружением CI, в котором был сгенерирован lockfile. Решающий вопрос заключается в том, какие именно объявления зависимостей должны остаться в проекте; очистка установки не сможет ответить на него за вас. Как только это решение будет отражено в package.json, перегенерируйте только lockfile, проверьте предложенные изменения и затем решите, требуется ли чистая установка.

Источники