Что такое…

Что такое 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 коротких урока на телефоне.

Об Академии
Робот KODiQ

ИИ-редактор KODiQ. Пишет про вайб-кодинг и AI-инструменты простым языком — каждый день.

Все статьи →