Денис Тарелкин 16 ноября 2026

Почему Docker заново ставит зависимости после правки одной строки

Разбираем, почему Docker повторно запускает npm ci, как переиспользовать слой зависимостей и где искать причину в журнале сборки.
Почему Docker заново ставит зависимости после правки одной строки

Если Dockerfile сначала копирует весь проект, а потом запускает npm ci, правка обычного файла приложения может заставить Docker повторно установить зависимости. Переставьте команды так, чтобы установка зависела от манифеста и lock-файла. Тогда при изменении кода Docker сможет использовать уже готовый слой зависимостей.

Где сборка теряет кеш

Docker проверяет инструкции и входные файлы, чтобы решить, можно ли взять готовый результат. Если вход инструкции COPY изменился, следующие инструкции в этой цепочке будут выполнены заново. Типичный пример:

        FROM node:24
WORKDIR /app
COPY . .
RUN npm ci
CMD ["node", "index.js"]
    

Здесь изменение index.js меняет вход для COPY . .. Шаг RUN npm ci идёт после него и в таком сценарии выполняется повторно, хотя package.json и package-lock.json остались прежними.

Как отделить зависимости от кода

Docker рекомендует сначала копировать редко меняющиеся файлы. Для небольшого Node.js-сервиса с lock-файлом это выглядит так:

        FROM node:24
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
CMD ["node", "index.js"]
    

Теперь правка index.js затрагивает второе копирование. Установку зависимостей можно взять из кеша. Когда меняется lock-файл, Docker снова запускает npm ci, как и требуется. Добавьте node_modules, .git и локальные артефакты в .dockerignore, если они не нужны внутри образа: так они не попадут в контекст сборки.

У проектов с npm workspaces или скриптами установки бывают дополнительные входы. Если установка читает манифесты пакетов, конфигурацию npm или файлы из репозитория, скопируйте нужные файлы до npm ci. Этот порядок должен отражать то, от чего установка реально зависит.

У Docker и npm разные кеши

Кеш BuildKit позволяет целиком пропустить шаг RUN npm ci, когда его входы совпадают. Кеш npm хранит скачанные пакеты и помогает установке, если шаг всё-таки пришлось выполнять. Эти механизмы видны в разных местах. Статус CACHED рядом с шагом означает, что сборщик взял готовый слой. Если в выводе появился лог npm, установка запустилась, хотя часть пакетов могла приехать из локального кеша.

Команда npm ci устанавливает зависимости по lock-файлу. Если версии в манифесте и lock-файле разошлись, она завершится ошибкой. Это полезно для CI: новая сборка не обновит зависимости молча. Когда в тесте меняете зависимости, обновите оба файла штатной командой и только после этого запускайте сборку. Ручная правка одного файла может проверять согласованность манифеста вместо скорости сборки.

После разделения COPY можно добавить cache mount, если установку часто запускает изменение lock-файла. Для образа, в котором npm работает от root и хранит кеш в стандартном месте, пример выглядит так:

        RUN --mount=type=cache,target=/root/.npm npm ci
    

Если сборка идёт от другого пользователя или npm использует другой каталог кеша, сначала проверьте путь. Эта строка влияет на стоимость повторного запуска установки. Слой с уже установленными зависимостями по-прежнему выгоднее переиспользовать целиком, когда манифест не менялся.

Как снять чистые и повторные сборки без путаницы

Для сравнения двух Dockerfile сначала убедитесь, что оба собирают одно приложение. Зафиксируйте базовый образ, платформу, lock-файл, версию сборщика и состав контекста. Затем выделите две отдельные копии исходников или изолированные сборщики. Это снижает риск, что один вариант случайно получит кеш от другого. Если исходники общие, перед каждой серией возвращайте их к одной исходной версии.

В таблицу заносите общий результат и время ключевого шага. Для холодного прогона нужно явно описать, какие кеши очищены или обходятся. Флаг --no-cache заставляет выполнить шаги заново, но это отдельное условие от скачивания базового образа. Для повторного прогона кеш должен сохраниться. Иначе вы проверите, сколько идёт чистая сборка, а эффект переноса COPY в данных не появится.

Сценарий Dockerfile с общим COPY Dockerfile с отдельным COPY манифеста
Холодная сборка без слоя зависимостей Запускает установку Запускает установку
Повтор после изменения только файла приложения Запускает установку Переиспользует слой при совпавших входах
Повтор после изменения lock-файла Запускает установку Запускает установку

Здесь перечислено ожидаемое поведение кеша по правилам Docker. Числа из конкретной сборки добавляйте после прогона. Для изменений одной строки удобно менять содержимое, а не только время записи файла: Docker не включает время изменения файла в расчёт кеша для таких проверок.

Почему на CI всё может снова собираться с нуля

На рабочей машине следующий запуск часто попадает на тот же сборщик. У одноразового раннера предыдущего локального кеша может не быть. BuildKit поддерживает экспорт и импорт кеша, поэтому CI может сохранить результаты сборки и забрать их на следующем запуске. Выберите подходящее хранилище и проверьте по логам, что кеш импортировался до выполнения нужного шага.

Есть и другой источник расходов. Даже если слои сохраняются, клиент отправляет в сборку контекст. Docker применяет .dockerignore к файлам контекста. Если туда попали локальные зависимости, артефакты тестов и большие архивы, на передачу может уйти больше времени, чем на саму повторную сборку. Посмотрите на размер контекста в выводе BuildKit и проверьте, какие каталоги действительно нужны Dockerfile.

Что проверить, если шаг по-прежнему запускается

Начните с первого шага в выводе, который перестал показывать CACHED. Если изменилась строка до установки или файл, который она копирует, найдите этот вход. Для монорепозитория проверьте манифесты пакетов и конфигурацию. Для CI проверьте, что предыдущий кеш доступен и вы запускаете сборку тем же способом. Если отличаются образ или платформа, зафиксируйте это как отдельный сценарий.

После правки проверьте, что контейнер действительно работает. Запустите приложение и один короткий тест. Затем измените зависимость, обновите lock-файл и убедитесь, что установка выполнилась снова. Так вы проверите обе стороны задачи: после правки кода сборка использует готовый слой, а после изменения зависимостей получает актуальный набор пакетов.

Как понять, что именно ускорилось

Сохраните лог каждого прогона рядом с изменением, которое его вызвало. Подпишите, меняли ли вы код приложения, пакет или сам Dockerfile. В логе отдельно отметьте длительность передачи контекста, шага установки и всей сборки. Если один вариант быстрее по общему времени, а установка по-прежнему запускается, разница могла прийти от другого шага или сети.

Сделайте по несколько повторов и покажите диапазон рядом с медианой. Для прогона после изменения кода можно чередовать две короткие версии одного файла, каждый раз проверяя, что результат для текущего состояния уже не лежит в кеше. Иначе возвращение к прежнему содержимому может дать попадание на другом шаге и смазать сравнение.

У удачного результата есть простая проверка. После правки кода у установки виден статус CACHED, приложение запускается с новой версией файла. После изменения зависимостей установка выполняется и использует обновлённый lock-файл. Разница между этими двумя прогонами важнее одного красивого числа из лога.

Три сборки, которые показывают разницу

Сохраните варианты как Dockerfile.before и Dockerfile.after и соберите оба с выводом BuildKit в обычном тексте:

        docker build --progress=plain -f Dockerfile.before -t cache-demo:before .
docker build --progress=plain -f Dockerfile.after -t cache-demo:after .
    

Затем измените строку в index.js, повторите обе команды и найдите шаг с npm ci. В варианте с разделёнными копированиями для этого шага должен появиться статус CACHED. После изменения зависимостей и обновления lock-файла обе сборки должны снова выполнить установку.

Для сравнения времени используйте одну версию базового образа и одинаковый контекст. Снимайте отдельно чистую сборку, повтор после правки кода и повтор после изменения зависимостей. Если сборки выполняются на одноразовых CI-раннерах, отдельно проверьте внешний кеш BuildKit. Без него следующий запуск на новом раннере не увидит слои прошлого запуска.

Комментарии