Чем COPY отличается от ADD? Когда что использовать?

Правило выбора

# syntax=docker/dockerfile:1.7
FROM node:22-bookworm-slim
WORKDIR /app

# COPY — для исходников, манифестов, конфигов
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY src ./src

# ADD с checksum — для remote бинаря
ADD --checksum=sha256:9b1f5d... https://example.com/tool-1.2.0.tar.gz /tmp/
RUN tar -xzf /tmp/tool-1.2.0.tar.gz -C /opt && rm /tmp/tool-1.2.0.tar.gz

# ADD локального архива — распаковывается автоматически
ADD rootfs.tar.gz /

Различие

COPY src dst делает ровно одно — копирует файлы из build context в слой образа. ADD делает то же плюс две магии:

• Автораспаковка локального tar-архива (.tar, .tar.gz, .tgz, .tar.bz2, .tar.xz) в целевую директорию.
• Скачивание по URL (ADD https://...) — без verify checksum, без retry policy.

Начиная с BuildKit (Dockerfile 1.4+) у ADD появились флаги --checksum=sha256:<hex> и --keep-git-dir для git-источников.

Альтернатива через RUN

RUN curl -fsSL -o /tmp/tool.tgz https://example.com/tool-1.2.0.tar.gz \
 && echo '9b1f5d...  /tmp/tool.tgz' | sha256sum -c - \
 && tar -xzf /tmp/tool.tgz -C /opt \
 && rm /tmp/tool.tgz

Явно: один слой, проверка целостности, удаление архива в том же слое (иначе он останется в image).

Подводные камни

• ADD https://... без --checksum — supply chain риск: URL может изменить содержимое без смены хеша.
• ADD распаковывает только локальные tar; remote tar просто скачивается как файл.
• ZIP, 7z, RAR ADD не распаковывает — нужен unzip в RUN.
• COPY --from=stage — единственный путь в multi-stage; у ADD --from такого нет.
• Cache invalidation: ADD https://... инвалидирует кэш только по URL-строке, не по контенту — без --checksum можно получить stale бинарь.
• COPY --chown=user:group и --chmod=0755 работают и в ADD, но менять права в одном RUN бывает чище.
• Большие архивы через ADD увеличивают размер слоя на распакованный объём — иногда выгоднее multi-stage с COPY --from.

• Использовать ADD как более короткий COPY без причины.
• Скачивать бинарники через ADD по URL без checksum verification.
• Не учитывать, что автоматическая распаковка может удивить следующего maintainer.

• Выбирает COPY как безопасный дефолт.
• Называет реальные дополнительные возможности ADD.
• Понимает риск remote artifacts и прозрачности supply chain.