re:re:actable
Урок 073 минуты чтения

Чем COPY отличается от ADD, а ARG от ENV

На этой странице
Кратко

COPY просто копирует файлы из build context или другого stage. ADD умеет больше — скачивать по URL, клонировать git-репозиторий и автоматически распаковывать локальные tar-архивы, — поэтому его поведение менее очевидно; по умолчанию используют COPY. ARG — параметр только сборки, задаётся через --build-arg и в работающем контейнере недоступен. ENV — переменная окружения, которая сохраняется в образе и видна приложению при запуске. Ни тот, ни другой не подходят для секретов.

Вопрос

Чем COPY отличается от ADD, а ARG от ENV?

COPY и ADD

COPY package.json package-lock.json ./
COPY --chown=node:node src ./src
COPY --from=build /app/dist ./dist
ADD app.tar.gz /opt/app/                              # распакует архив
ADD https://example.com/tool.tar.gz /tmp/             # скачает, но не распакует
ADD --checksum=sha256:4c7e... https://example.com/tool /usr/local/bin/tool
ADD https://github.com/org/repo.git#v1.2.0 /src       # клонирует репозиторий
COPYADD
Файлы из contextДаДа
Из другого stage (--from)ДаДа
URLНетДа
Git-репозиторийНетДа
Распаковка локального tarНетДа, автоматически

Рекомендация Docker: COPY для всего обычного, ADD — осознанно, когда нужна загрузка с проверкой --checksum или распаковка архива.

ARG и ENV

ARG NODE_VERSION=24
FROM node:${NODE_VERSION}-alpine
 
ARG APP_VERSION=dev
ENV APP_VERSION=${APP_VERSION}     # пробросить значение сборки в runtime
ENV NODE_ENV=production
docker build --build-arg NODE_VERSION=22 --build-arg APP_VERSION=1.4.0 -t api .
docker run -e NODE_ENV=development api   # ENV можно переопределить при запуске
ARGENV
Когда доступенТолько во время сборкиПри сборке и в контейнере
Как задать--build-argENV в Dockerfile, -e при docker run
Есть в образеНет (но может остаться в истории)Да, виден в docker inspect
Область видимостиДо конца stage; до FROM — только для FROMДо конца stage и в наследниках
Влияние на кэшИзменение значения инвалидирует инструкции, где он используетсяИзменение инвалидирует последующие слои

Область видимости ARG

ARG NODE_VERSION=24
FROM node:${NODE_VERSION}-alpine
RUN echo $NODE_VERSION        # пусто! ARG до FROM вне stage
 
ARG NODE_VERSION              # повторное объявление без значения
RUN echo $NODE_VERSION        # 24

В multi-stage каждый stage объявляет нужные ARG сам.

Почему оба не годятся для секретов

ARG NPM_TOKEN
RUN echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc && npm ci

Значение ARG попадает в метаданные сборки и может быть видно в docker history, а файл .npmrc остаётся в слое. ENV с паролем вообще виден любому через docker inspect. Правильный способ — RUN --mount=type=secret, см. урок про секреты.

Частые ошибки

  • Использовать ADD для обычного копирования и случайно распаковать архив.
  • Ожидать, что ARG будет доступен приложению в runtime.
  • Объявить ARG до FROM и удивляться пустому значению внутри stage.
  • Передавать токены и пароли через ARG или ENV.

Что важно помнить

  • По умолчанию — COPY; ADD — только для URL с --checksum, git или распаковки tar.
  • ARG параметризует сборку, ENV настраивает окружение процесса.
  • Шаблон ARG X → ENV X=${X} переносит значение сборки (например, версию) в runtime.

Мини-шпаргалка

  • COPY — просто копирование, ADD — плюс URL, git и tar.
  • ARG — build-time, --build-arg.
  • ENV — runtime, -e переопределяет.
  • ARG до FROM виден только в FROM.
  • Секреты — --mount=type=secret.

Документация

Docker: Dockerfile reference — ADD, Docker: Dockerfile reference — ARG, Docker: Variables in builds.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам