Чем 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 ./distADD 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 # клонирует репозиторийCOPY | ADD | |
|---|---|---|
| Файлы из 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=productiondocker build --build-arg NODE_VERSION=22 --build-arg APP_VERSION=1.4.0 -t api .
docker run -e NODE_ENV=development api # ENV можно переопределить при запускеARG | ENV | |
|---|---|---|
| Когда доступен | Только во время сборки | При сборке и в контейнере |
| Как задать | --build-arg | ENV в 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.