본문 바로가기
2026년 5월 16일2분 읽기

Docker buildkit 멀티스테이지에서 npm install 캐시가 매번 무효화돼요

김
김영삼
조회 614댓글 3

CI에서 Docker 이미지 빌드 시간이 너무 깁니다. 멀티스테이지 + COPY package.json 패턴을 썼는데 캐시가 자꾸 무효화돼서 매번 npm install이 처음부터 돕니다.

FROM node:22-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev

FROM node:22-alpine AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM node:22-alpine
WORKDIR /app
COPY --from=build /app/.next ./.next
CMD ["node", "server.js"]

로컬에서 빌드는 잘 되는데, GitHub Actions에서 매번 cache miss입니다. cache-from, cache-to 다 설정했는데도. 어떻게 정착해야 하나요?

댓글 3

김김영삼6개월 전

BuildKit 캐시는 함정이 많은데, 가장 흔한 두 가지가 작용한 것 같습니다.


원인 1 — COPY가 mtime을 본다


BuildKit은 파일 내용 해시로 캐시 키 결정합니다. 그런데 checkout 액션이 mtime을 현재 시각으로 설정해서, 내용은 같아도 메타데이터 변경으로 캐시 miss가 납니다. 정확히는 BuildKit이 이걸 무시해야 하는데 GHA 환경에서 종종 실패합니다.


해결:


# GHA workflow
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Restore file mtimes # 이거 핵심
run: |
git ls-files | xargs -I{} touch -d "$(git log -1 --format="@%ct" -- {})" {}

원인 2 — cache mount를 안 씀


현재는 node_modules를 통째로 캐시 layer에 넣고 있는데, 이건 package.json이 1글자만 바뀌어도 전체 무효화. BuildKit cache mount를 쓰면 npm cache 자체를 영속 캐시합니다:


# syntax=docker/dockerfile:1.7
FROM node:22-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm \
npm ci --omit=dev --prefer-offline

이렇게 하면 .npm 캐시가 build 간 공유돼서 package.json 바뀌어도 download 단계는 거의 캐시 hit.


원인 3 — cache-from 형식 잘못


GHA에서 BuildKit cache는 두 가지 backend가 있는데:



  • type=gha — GitHub Actions cache (10GB 한도)

  • type=registry — 이미지 레지스트리에 캐시 push (한도 없음)


monorepo에서 큰 캐시면 registry 쪽이 안정적입니다. type=gha는 10GB 한도 넘으면 LRU 삭제돼서 캐시가 사라지는 케이스가 많아요.


- uses: docker/build-push-action@v6
with:
cache-from: type=registry,ref=ghcr.io/org/cache:buildcache
cache-to: type=registry,ref=ghcr.io/org/cache:buildcache,mode=max

mode=max가 중요 — 모든 layer 캐시. 기본 mode=min은 final image만.


이 세 가지 적용하면 빌드 시간이 보통 5분 → 30초로 떨어집니다.

서서버지기영호6개월 전

cache mount의 sharing 옵션도 확인하세요. --mount=type=cache,target=/root/.npm,sharing=locked로 동시 빌드 안전성 확보. 동시 빌드 시 lock contention 생기면 sharing=private로 격리.

ddevops_kim(guest)6개월 전
pnpm으로 옮기는 것도 고려해보세요. content-addressable store라 BuildKit cache mount와 궁합이 매우 좋습니다. npm install이 14s → 2s 됐어요.
Ctrl+Enter로 등록