Текст и данные · Инструкция
Dockerfile COPY или ADD: что выбрать
COPY и ADD оба помещают данные в файловую систему image, но их семантика различается.
Короткий ответ
Для обычного переноса локальных файлов в образ выбирайте COPY: он проще и явнее. ADD нужен, когда вы осознанно используете его дополнительные возможности.
Чем COPY и ADD отличаются по семантике
Обе инструкции добавляют файлы в filesystem image, но ADD умеет больше. Поэтому Dockerfile легче читать и отлаживать, когда простой перенос выражен через COPY. Docker Docs описывает ADD как добавление локальных или удалённых файлов и каталогов, а COPY — как копирование файлов и каталогов. Дополнительная семантика ADD не нужна для обычного package.json или исходного кода.
Совет: Для локального source code начинайте с COPY — intent Dockerfile читается сразу.
Как выбрать COPY или ADD
- Определите, локальный ли источник.
- Для обычных локальных файлов начните с COPY.
- Если нужен ADD, запишите конкретную дополнительную функцию.
- Проверьте build context и .dockerignore.
- Соберите образ и проверьте конечный путь.
Предупреждение: Не меняйте COPY на ADD ради обхода ошибки build context: это не исправляет отсутствующий источник.
Нюансы: build context и архив tar
Учитывайте build context и .dockerignore: проблема «файл не найден» часто связана не с выбором COPY/ADD, а с тем, что источник отсутствует в доступном context или исключён. Для удалённых артефактов важны воспроизводимость и проверка содержимого. Версию и checksum лучше фиксировать явно, а не превращать ADD в непрозрачный загрузчик.
Важно: Удалённые артефакты фиксируйте по версии/контрольной сумме, если workflow это допускает.
Пример: package.json из build context
`COPY package*.json ./` явно переносит manifests из build context. Для этой задачи ADD не даёт полезного преимущества.
Когда COPY — лучший выбор
Для `package.json`, исходного кода, конфигов и других локальных файлов из build context используйте COPY. Так Dockerfile явно показывает простое копирование без дополнительной семантики. Если источник не найден, сначала проверьте context и `.dockerignore`, а не меняйте COPY на ADD.
Когда ADD оправдан
ADD имеет дополнительные возможности для удалённых источников и расширенной обработки данных; используйте их только когда это действительно часть сборки. Для воспроизводимости фиксируйте версии и checksum там, где применимо. Не превращайте ADD в универсальный загрузчик — отдельный fetch-step часто проще контролировать и кэшировать.
COPY и ADD: практическая разница
- COPY. обычные локальные файлы и каталоги из build context. поведение проще и предсказуемее
- ADD. когда нужна дополнительная функция ADD, например поддерживаемый удалённый источник или распаковка локального tar. не использовать только ради копирования обычного файла
- обе. копирование с параметрами Dockerfile. путь источника должен находиться в доступном build context/источнике
Что учитывать
Условия меняются. Страница отражает состояние на 2026-09-22; при расхождении с официальной документацией приоритет у первоисточника.
Источники и проверка
Фактическая часть сверена по первичным источникам (в т.ч. Dockerfile reference). Пример и формулировки — редакция N1RO на 2026-09-22.