Что такое lock-файл — и почему «у меня работает» больше не аргумент

Ты скинул проект другу. Тот же репозиторий, та же команда установки — и у него всё падает. Ты пожимаешь плечами: «у меня работает».
Вот неожиданная штука: скорее всего, у вас реально разный код. Не твой — чужой. Библиотеки, которые вы оба «просто установили», приехали разных версий. И виноват не друг, а одна строчка в package.json, которая выглядит как версия, но версией не является.
В package.json записана не версия, а диапазон
Открой package.json и посмотри на зависимости. Там что-то вроде "react": "^19.1.0".
Кажется, что это «версия 19.1.0». На самом деле ^ — это оператор диапазона. Он означает: любая версия, пока не сменился первый номер. То есть 19.1.0, 19.2.7, 19.9.4 — всё подходит. Про то, что означают эти три числа, есть отдельный разбор — семантические версии.
И вот что происходит дальше. Ты установил пакет в понедельник — приехала 19.1.0. Друг клонировал проект в пятницу, а в среду вышла 19.2.0. У него установится она. Файл package.json у вас одинаковый до буквы, а код в node_modules — разный.
Обычно новая минорная версия ничего не ломает. Но «обычно» — это не «всегда», и разбираться в чужом баге на чужой версии особенно весело.
Что лежит в lock-файле
Lock-файл — это тот же список, но записанный до конца.
- Точная версия каждого пакета: не «19.x», а
19.2.0. - Все зависимости твоих зависимостей. Ты поставил 20 пакетов, а в папке их 600 — вот они все и перечислены.
- Адрес архива и хеш целостности: проверка, что скачался ровно тот файл, а не подменённый.
Аналогия простая. package.json — список покупок: «молоко, хлеб». Lock-файл — чек: молоко такое-то, 3,2%, партия такая-то. По списку двое принесут разное. По чеку — одно и то же.
Про хеш стоит сказать отдельно, потому что это уже не про удобство, а про безопасность. Каждая запись в lock-файле хранит контрольную сумму архива. При установке она пересчитывается: не сошлась — установка падает. Так ты замечаешь, что вместо привычного пакета приехало что-то другое, — а атаки на цепочку поставок в мире пакетов давно перестали быть теорией.
У каждого менеджера пакетов свой lock-файл: у npm это package-lock.json, у pnpm — pnpm-lock.yaml, у yarn — yarn.lock. И друг друга они не читают: перешёл с npm на pnpm — старая гарантия не переехала, нужен новый lock. Поэтому один проект — один менеджер, без «а я привык».
Почему удалять lock-файл — худшее из лечений
Самый популярный совет в интернете, когда установка падает: удали node_modules и package-lock.json, поставь заново.
Иногда это правда помогает — и именно поэтому опасно. Помогает оно так: npm выбрасывает зафиксированный набор версий и подбирает новый, посвежее. Твоя ошибка исчезает вместе со старой версией пакета. Но заодно бесшумно меняются сотни других версий, которых ты не трогал и не проверял.
Ты не починил одну поломку. Ты обменял её на неизвестное количество будущих — и потерял единственную запись о том, как выглядела рабочая сборка.
Правильный порядок при упавшей установке: сначала прочитать ошибку (в разборе про npm install — четыре типовые причины), удалить node_modules, почистить кэш. Lock-файл — последнее, что трогают, и только осознанно.
Как с ним жить
Три правила, и проблема закрыта навсегда.
Коммить lock-файл в git. Всегда. Это не мусор и не артефакт сборки — это часть проекта. Без него совместная работа превращается в лотерею.
Локально ставь npm install. Он уважает lock-файл и обновляет его, когда ты осознанно добавляешь или удаляешь пакет. Изменения в lock-файле после npm install <пакет> — это нормально, их и надо закоммитить.
На сервере и в CI ставь npm ci. Эта команда читает только lock-файл, ставит ровно перечисленное, не трогает package.json — и падает, если lock и package.json разошлись. То есть сборка либо точно повторяет твою, либо честно кричит. У pnpm то же самое делает pnpm install --frozen-lockfile, у yarn — yarn install --immutable.
Бонус: npm ci заметно быстрее, потому что ему не нужно ничего подбирать — он просто скачивает список.
Нужно ли коммитить lock-файл, если я один в проекте?
Да. «Один» — это ты сегодня и ты через три месяца, плюс сервер, куда ты деплоишь. Это уже три разные машины, и им нужен одинаковый набор версий.
Что делать, если при слиянии веток lock-файл конфликтует?
Не разбирай его руками — он машинный. Возьми версию из основной ветки, потом выполни npm install: npm сам перестроит lock-файл под текущий package.json. Полученный результат закоммить.
Теперь, когда друг скажет «у меня падает», ты первым делом спросишь не «а что за ошибка», а «lock-файл в репозитории есть?». В половине случаев разговор на этом и закончится.
Курс «Профессия 2027: ИИ-архитектор»: шаг за шагом от основ компьютера до своего приложения и первых клиентов. 543 коротких урока на телефоне.





