pnpm 버전 업그레이드로 인한 로컬 node_modules 오염 및 Docker 빌드 컨텍스트 유입 해결

A Docker Build Failure That Had Nothing to Do With Docker

Janice2026년 6월 14일2분intermediate

AI 요약

Context

PNPM Monorepo 구조에서 CI/CD 환경과 달리 로컬 Docker 빌드 시에만 MODULE_NOT_FOUND 에러가 발생하는 현상 발생. PNPM 9.x에서 10.x로의 버전 업그레이드 이후 로컬 Dependency Layout이 최신화되지 않은 상태로 유지된 것이 원인임.

Technical Solution

PNPM 버전 변경에 따른 Symlink 구조 변화로 인해 기존 로컬 node_modules의 유효성 상실 파악
pnpm install 실행을 통한 로컬 Dependency Link 구조의 완전한 재구성 및 최신화
root-level에 한정되었던 .dockerignore 설정을 **/node_modules 형태로 확장하여 모든 Workspace 수준의 의존성 디렉토리 배제
Docker Build Context에 로컬의 Stale한 파일이 유입되는 경로를 차단하여 환경 간 일관성 확보
Monorepo 특성을 고려한 .next 빌드 아티팩트의 빌드 컨텍스트 제외 설정 적용

실천 포인트

1. Monorepo 환경의 .dockerignore 설정 시 root 외에 모든 하위 디렉토리의 node_modules를 포함하고 있는지 확인

2. 패키지 매니저(PNPM, Yarn 등) 버전 업데이트 후에는 반드시 의존성 트리를 재구성하여 Symlink 정합성 검토

3. CI/CD와 로컬 빌드 결과가 다를 경우, .dockerignore 누락으로 인한 Local-only 파일의 Build Context 유입 가능성 우선 조사

태그

#Docker #dependency-management #Monorepo #pnpm #Build Context

원문 읽기