빠른 비교

# 일반 파일과 디렉터리 복사
COPY package.json package-lock.json ./
COPY src/ ./src/

# 멀티 스테이지 산출물 복사
COPY --from=build /app/dist ./dist

# tar 자동 해제나 원격 source가 필요한 경우에만 ADD 검토
ADD archive.tar.gz /opt/archive/
ADD --checksum=sha256:<hash> https://example.com/file.tar.gz /tmp/

문법

COPY는 빌드 컨텍스트와 stage에서 파일을 명시적으로 가져온다

대부분의 Dockerfile에서는 COPY가 기본 선택입니다. COPY는 build context, 다른 build stage, named context, image에서 파일이나 디렉터리를 이미지 파일시스템으로 복사합니다. 마지막 인자는 항상 대상 경로이며, 여러 source를 지정하면 대상은 디렉터리여야 합니다.

COPY package.json package-lock.json ./
COPY ["file with spaces.txt", "/data/"]
COPY --from=build /app/server /usr/local/bin/server
COPY --chown=app:app --chmod=755 entrypoint.sh /entrypoint.sh

COPY --from은 멀티 스테이지 빌드에서 가장 중요한 변형입니다. 빌드 stage 전체를 가져오지 않고 필요한 산출물만 복사해야 최종 이미지가 작고 예측 가능해집니다.

ADD는 추가 동작이 필요한 경우에만 쓴다

ADD는 COPY와 비슷하지만 추가 동작이 있습니다. 로컬 tar archive를 자동으로 해제할 수 있고, BuildKit 기준으로 원격 URL이나 Git source를 source로 다룰 수 있습니다. 이 편의 기능 때문에 의도하지 않은 압축 해제나 원격 다운로드가 빌드에 섞일 수 있으므로, 단순 복사에는 COPY를 쓰는 편이 명확합니다.

# 로컬 tar archive를 이미지 안에서 자동 해제
ADD archive.tar.gz /opt/app/

# 원격 리소스는 checksum을 함께 두어 변경을 검증
ADD --checksum=sha256:<hash> https://example.com/archive.tar.gz /tmp/

원격 파일을 받아야 한다면 ADD <url>보다 RUN curl ... && echo '<hash> file' | sha256sum -c - 같은 명시 흐름이 더 통제하기 쉬울 때가 많습니다. 반대로 ADD --checksum처럼 Dockerfile 기능으로 검증을 함께 표현할 수 있으면 빌드 정의 안에서 의도를 읽기 쉽습니다.

선택 기준

COPY . .는 빠르지만 build context 전체가 이미지에 들어갈 수 있습니다. .dockerignore와 함께 설계하지 않으면 .git, 테스트 산출물, 로컬 설정 파일까지 복사될 수 있습니다. COPY와 ADD의 선택 이전에 build context 범위가 올바른지 확인해야 합니다.

주의할 점

# 의도가 불명확한 패턴
ADD . /app

# 더 명확한 패턴
COPY package.json package-lock.json ./
RUN npm ci
COPY src/ ./src/