Как исправить несовпадение package.json и package-lock.json при npm ci

#Что означает ошибка и когда она возникает

Команда npm ci выполняет воспроизводимую установку: если package-lock.json расходится с заявленными зависимостями package.json, npm останавливается и не исправляет lock-файл автоматически. Это полезная защита при развёртывании. Причину следует устранять в изменениях проекта, а не удалением lock-файла.

#Как отличить возможные причины

#Пошаговая диагностика и устранение

1. Убедитесь, что падает именно npm ciВ терминале VS Code в корне проекта выполните npm ci только если это безопасная копия проекта: команда удалит её node_modules. Для рабочего каталога сперва изучите уже имеющийся журнал сборки; найдите сообщение о несоответствии package.json и package-lock.json. Не воспринимайте EACCES или отсутствие lock-файла как одну и ту же проблему.
2. Проверьте, что оба файла принадлежат одному проектуОткройте папку с package.json и package-lock.json. В терминале используйте node --version, npm --version, git status --short, затем git diff -- package.json package-lock.json. Если используется рабочее пространство npm workspaces, запускайте команды из корня соответствующего проекта и учитывайте файлы рабочих пакетов.
3. Определите, что менялось в зависимостяхСравните поля dependencies/devDependencies в package.json с соответствующим lock-файлом, обратите внимание на удалённые, добавленные или изменённые прямые зависимости. Если файлы принадлежат разным веткам, восстановите верную пару из одного коммита; не смешивайте случайный старый lock с новой схемой зависимостей.
4. Создайте отдельную ветку или копию для исправленияПеред изменениями сохраните незакоммиченные файлы и создайте новую ветку Git (например, через интерфейс VS Code «Управление исходным кодом» → имя текущей ветки → Создать ветку). Не запускайте пересоздание lock-файла на рабочем сервере: исправление выполняют в исходниках и проверяют перед развёртыванием.
5. Согласуйте lock-файл безопасной командойЕсли изменения в package.json намеренные, в доверенной копии выполните npm install --package-lock-only --ignore-scripts. Параметр --package-lock-only обновляет lock без изменения установленного дерева node_modules; --ignore-scripts не запускает хуки пакетов в этом шаге. Проверьте результат git diff; возможны ошибки реестра и peerDependencies — разберите их, не добавляйте --force.
6. Убедитесь, что не пропали полезные измененияПосмотрите git diff -- package.json package-lock.json. Согласован ли реальный список прямых зависимостей с заданием и не произошло ли неожиданной массовой смены версий? Если изменение неожиданно, верните файлы из сохранённого коммита и разберите причину. Не удаляйте package-lock.json ради успешного npm install.
7. Проверьте воспроизводимость в чистой копииСкопируйте проект в отдельный каталог без конфиденциальных файлов и неподтверждённых локальных пакетов. Выполните npm ci в этой копии; убедитесь, что зависимости установились. Учтите: команда очищает node_modules перед установкой и может запускать скрипты пакетов, поэтому доверяйте исходникам и сборочному окружению.
8. Завершите исправление и предусмотрите откатВыполните предусмотренные scripts тестов (например, npm run build, если команда есть), сохраните в Git оба файла с согласованными изменениями и повторите сборку CI. Если проверка не проходит из-за версий или специфических флагов, приложите журнал npm и сохранённые параметры установки. Для отката верните package.json и package-lock.json одним согласованным коммитом, а не по отдельности.
9. Команды для отдельных ситуацийВыберите только подходящий вариант. Это не одна последовательность: часть команд диагностирует проблему, а часть меняет настройки или данные.
   Выберите подходящий вариант — это не команды для последовательного выполнения

   Вариант 1Только чтение, выполняйте в корне своего Git-проекта.

   Linux · Терминал (Bash)КомандаКопировать всёВыделить

   Только чтение, выполняйте в корне своего Git-проекта. Если Git не используется, сравните файлы через редактор и сохраните резервную копию.

   node --version

   npm --version

   git status --short

   git diff -- package.json package-lock.json

   Вариант 2В копии проекта: меняет package-lock.json, но не должен менять node_modules.

   Linux · Терминал (Bash)С осторожностьюКопировать всёВыделить

   В копии проекта: меняет package-lock.json, но не должен менять node_modules. Параметр --ignore-scripts отключает запуск пакетных скриптов именно в этой диагностической операции.

   npm install --package-lock-only --ignore-scripts

   Команда может изменить состояние системы или её настройки. Проверьте параметры и последствия перед запуском.

   Вариант 3Только в чистой копии и после сохранения данных: удаляет локальный node_modules, затем может запускать сцен…

   Linux · Терминал (Bash)С осторожностьюКопировать всёВыделить

   Только в чистой копии и после сохранения данных: удаляет локальный node_modules, затем может запускать сценарии установки из доверенных зависимостей.

   npm ci

   Команда может изменить состояние системы или её настройки. Проверьте параметры и последствия перед запуском.

#Минимальный пример и проверка на тестовом проекте

{
  "dependencies": {"example-library": "^2.0.0"}
}

#Проверка результата и действия при неуспехе

В чистой копии npm ci завершается успешно без изменения package.json и package-lock.json, а сборка/тесты проходят. Если после исправления локально CI снова падает, сравните версии Node/npm, .npmrc, параметры install-links/legacy-peer-deps и используемый рабочий каталог сборки.