Dockerfile 순서 하나 바꿨다고 빌드가 10배 빨라진 이유

문제 발생

애플리케이션 코드 한 줄만 수정했을 뿐인데, Docker 빌드가 매번 npm install부터 처음부터 다시 실행해 몇 분씩 걸리는 문제가 있었습니다.

FROM node:24-alpine
WORKDIR /app
COPY . .              # 소스 전체를 먼저 복사
RUN npm install       # 이후 설치 — 소스가 바뀌면 이 단계도 캐시 무효화됨
CMD ["node", "server.js"]

원인 분석

Docker는 Dockerfile의 각 명령어(FROM, COPY, RUN 등)를 하나의 레이어로 만들고, 이전 빌드와 비교해 명령어와 그 입력(복사되는 파일 내용 포함)이 동일하면 그 레이어를 캐시에서 재사용합니다. 문제는 한 레이어의 캐시가 무효화되면 그 이후의 모든 레이어도 함께 무효화된다는 점입니다.

위 Dockerfile은 COPY . .로 소스 전체(애플리케이션 코드 포함)를 먼저 복사합니다. 코드를 한 글자만 고쳐도 이 COPY 레이어의 캐시가 깨지고, 그 아래에 있는 RUN npm install도 연쇄적으로 다시 실행됩니다 — 실제로는 의존성(package.json)이 전혀 안 바뀌었는데도 말입니다.

해결 방안

자주 바뀌는 파일일수록 Dockerfile 아래쪽에, 잘 안 바뀌는 파일일수록 위쪽에 둡니다. 의존성 목록(package.json, lockfile)은 소스 코드보다 훨씬 덜 바뀌므로, 의존성 설치에 필요한 파일만 먼저 복사하고 설치한 뒤에 나머지 소스를 복사합니다.

FROM node:24-alpine
WORKDIR /app

# 의존성 관련 파일만 먼저 복사 — 이 파일들이 안 바뀌면 아래 RUN도 캐시 재사용됨
COPY package.json package-lock.json ./
RUN npm install

# 소스 코드는 나중에 복사 — 코드만 바뀌어도 npm install은 다시 안 함
COPY . .

CMD ["node", "server.js"]

이렇게 하면 소스 코드만 수정했을 때 npm install 레이어는 캐시를 그대로 재사용하고, 마지막 COPY . .부터만 다시 실행되어 빌드 시간이 크게 줄어듭니다.

추가로, CI 환경에서는 이 로컬 레이어 캐시가 매번 초기화되는 경우가 많으므로 docker/build-push-action의 cache-from/cache-to(예: GitHub Actions 캐시 백엔드) 같은 원격 캐시 기능을 함께 설정해야 CI에서도 이 이점을 실제로 볼 수 있습니다.

공식 문서

• Docker Docs: Layer caching
• Docker Docs: Dockerfile best practices