Docker 레이어 캐싱 최적화 — Dockerfile 작성 순서가 빌드 속도에 미치는 영향에 대해 설명해주세요

gptonline.ai/ko에서도 비슷한 실무형 개발 팁을 볼 수 있습니다.

Docker 레이어 캐싱에서 Dockerfile 작성 순서는 빌드 속도에 직접적인 영향을 줍니다. 이유는 Docker가 Dockerfile을 위에서 아래로 순서대로 실행하면서, 각 명령의 결과를 레이어로 저장하고, 다음 빌드 때 동일하다고 판단되면 그 레이어를 재사용하기 때문입니다. 한 단계에서 캐시가 깨지면, 그 아래 단계들도 연쇄적으로 다시 빌드됩니다. 그래서 “무엇을 먼저 쓰느냐”가 빌드 시간 차이를 크게 만듭니다. (Docker Documentation)

핵심 원칙은 간단합니다. 변경이 적은 것부터 위에, 자주 바뀌는 것은 아래에 두는 것입니다. Docker 공식 문서도 레이어를 논리적으로 정렬하고, 비용이 큰 단계는 가능한 앞쪽에, 자주 변하는 단계는 뒤쪽에 두라고 설명합니다. 이렇게 하면 소스 코드 일부만 바뀌었을 때 의존성 설치나 시스템 패키지 설치 같은 무거운 단계는 그대로 캐시를 재사용할 수 있습니다. (Docker Documentation)

예를 들어 Node.js 프로젝트에서 아래처럼 작성하면 비효율적입니다.

FROM node:20
WORKDIR /app
COPY . .
RUN npm install
RUN npm run build

이 구조에서는 소스 코드 한 줄만 바뀌어도 COPY . . 레이어가 달라지므로, 뒤에 있는 npm install과 npm run build까지 다시 실행될 가능성이 큽니다. 반면 아래처럼 바꾸면 훨씬 유리합니다.

FROM node:20
WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci

COPY . .
RUN npm run build

이 경우 소스 파일만 바뀌고 package.json이나 lockfile이 그대로라면, 의존성 설치 단계는 캐시를 재사용하고 빌드만 다시 수행할 수 있습니다. Docker 문서도 이런 식으로 의존성 정의 파일을 먼저 복사하고, 자주 바뀌는 소스는 나중에 복사하는 패턴을 권장합니다. (Docker Documentation)

왜 이런 차이가 생기냐면, COPY와 ADD는 관련 파일들의 메타데이터를 바탕으로 캐시 유효성을 판단하기 때문입니다. 해당 단계에 포함된 파일 내용이 바뀌면 그 레이어는 새로 만들어지고, 그 이후 단계도 다시 실행됩니다. 반대로 파일 수정 시간만 바뀐 경우는 캐시 판정에 직접 쓰이지 않을 수 있습니다. (Docker Documentation)

실무적으로는 보통 이런 순서가 좋습니다. 먼저 FROM, 그다음 OS 패키지 설치나 런타임 준비처럼 잘 안 바뀌는 작업, 그다음 의존성 메타파일만 복사해서 패키지 설치, 마지막에 애플리케이션 소스 복사와 빌드/테스트를 둡니다. 이렇게 하면 코드 수정이 잦아도 가장 무거운 설치 레이어를 최대한 재사용할 수 있습니다. (Docker Documentation)

추가로 빌드 속도를 더 끌어올리려면 .dockerignore로 불필요한 파일을 빌드 컨텍스트에서 제외하는 것이 중요합니다. 빌드 컨텍스트가 크면 전송량이 늘고, 관련 없는 파일 변화로도 캐시가 깨질 가능성이 커집니다. Docker는 컨텍스트를 작게 유지하라고 권장합니다. (Docker Documentation)

또 하나는 멀티 스테이지 빌드입니다. 이것은 최종 이미지 크기를 줄이는 데 주로 쓰이지만, 빌드 단계와 런타임 단계를 분리해 Dockerfile 구조를 더 명확하게 만들고 캐시 전략을 세우기 쉽게 해줍니다. 특히 컴파일이 필요한 언어에서는 빌더 스테이지의 의존성 설치와 컴파일 결과를 분리하는 방식이 유용합니다. (Docker Documentation)

정리하면, Dockerfile 순서는 단순한 스타일 문제가 아니라 캐시 재사용률을 결정하는 성능 설계입니다.
좋은 순서는 대체로 이렇게 기억하면 됩니다.

잘 안 바뀌는 무거운 단계 → 의존성 파일 복사 및 설치 → 자주 바뀌는 소스 복사 → 최종 빌드

이 원칙만 지켜도 로컬 개발과 CI에서 빌드 시간이 눈에 띄게 줄어드는 경우가 많습니다. (Docker Documentation)

원하시면 다음 답변에서 Node.js / Python / Java 기준으로 “느린 Dockerfile vs 빠른 Dockerfile” 예시를 바로 비교해서 보여드리겠습니다.

더 많은 한국어 AI·개발 활용 팁은 gptonline.ai/ko에서도 확인할 수 있습니다.