핵심 정리

FROM node:22-alpine
WORKDIR /app

# 의존성 파일만 먼저 복사 — 소스 변경이 캐시에 영향 없음
COPY package.json package-lock.json ./
RUN npm ci

# 소스 코드는 나중에 — 자주 바뀌는 파일을 뒤에 둔다
COPY . .
RUN npm run build

구조 이해

어떤 빌드 최적화 포인트를 먼저 떠올리면 되나

빌드 컨텍스트 전송 — docker build 실행 시 현재 디렉터리 전체가 데몬으로 전송된다

docker build .의 마지막 .은 현재 디렉터리를 build context로 지정한다는 뜻입니다. Docker CLI는 이 디렉터리의 파일 전체를 Docker 데몬(또는 BuildKit)으로 전송합니다. 데몬이 원격 서버에 있다면 네트워크를 타고 전달되므로, node_modules나 .git 같은 대형 폴더가 포함되면 빌드 시작 전부터 느려집니다.

# context 크기 확인 전략 — 빌드 전 어떤 파일이 포함되는지 확인
docker build --no-cache --progress=plain . 2>&1 | grep "transferring context"

레이어 캐시 무효화 — 한 레이어가 바뀌면 그 이후 모든 레이어가 재빌드된다

Docker는 각 Dockerfile 지시어 결과를 레이어로 저장합니다. 이전 빌드와 동일한 지시어라면 캐시된 레이어를 재사용하지만, 어느 한 레이어라도 변경되면 그 이후 모든 레이어는 재실행됩니다. COPY 대상 파일의 내용이 바뀌면 해당 COPY 레이어부터 캐시가 깨집니다.

# 나쁜 예 — 소스 코드 한 줄만 바꿔도 npm ci가 다시 실행됨
COPY . .
RUN npm ci

# 좋은 예 — 소스 변경은 npm ci 캐시에 영향 없음
COPY package.json package-lock.json ./
RUN npm ci
COPY . .

COPY 순서로 캐시를 최대화 — 자주 바뀌는 파일을 나중에 복사한다

캐시 전략의 핵심은 변경 빈도가 낮은 파일을 앞에, 자주 바뀌는 파일을 뒤에 배치하는 것입니다. 의존성 파일(package.json, requirements.txt, go.mod)은 소스 코드보다 훨씬 덜 바뀌므로 먼저 복사해 npm ci나 pip install 레이어를 캐시합니다.

# Python 예시
COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt
COPY src/ ./src/
# requirements.txt가 안 바뀌면 pip install은 캐시 재사용

build context와 레이어 캐시는 서로 연결돼 있다

context에 들어간 파일이 바뀌면 관련 COPY 레이어부터 캐시가 깨집니다. 그래서 .dockerignore로 불필요한 파일을 빼는 것과 COPY 순서를 조정하는 작업은 사실 같은 문제의 두 면입니다. context가 더럽고 넓으면 캐시 전략도 같이 무너집니다.

체크포인트

주의할 점

# 잘못된 패턴
COPY . .
RUN npm ci

# README 한 줄 바뀌어도 npm ci 캐시가 다시 깨질 수 있음