pnpm 배포 시 Docker 11.19에서 "Cannot find module" 오류 해결

(dev.to)

pnpm 11.19.0~11.21.x 버전에서 발생한 배포 시 모듈 누락 오류는 Docker 빌드 과정에서 심볼릭 링크가 원본 소스 코드를 가리키며 발생하며, 이는 CI/CD 파이프라인을 통과하면서도 런타임 에러를 유발하는 치명적인 버그입니다.

이 글의 핵심 포인트

1pnpm 11.19.0~11.21.x 버전에서 `pnpm deploy` 시 워크스페이스 의존성이 `link:`(심볼릭 링크)로 생성되는 버그 발생
2Docker 빌드 시 `COPY` 명령어가 링크된 원본 소스를 포함하지 않아 `Cannot find module` 에러 유발
3기존의 `forceLegacyDeploy`나 `injectWorkspacePackages` 설정은 해당 버그 해결에 효과가 없었음
411.22.0 버전에서 의존성 해결 로직 수정을 통해 문제가 해결됨
5`readlink` 명령어를 통해 의존성이 `link:`인지 `file:`인지 확인하여 버그 여부를 판별 가능

이 글에 대한 공공지능 분석

왜 중요한가?

CI/CD 파이프라인의 모든 검증(Lockfile, Smoke test)을 통과하고도 실제 운영 환경에서만 에러가 발생하는 'Silent Failure'의 전형적인 사례이기 때문입니다.

어떤 배경과 맥락이 있나?

모노레포 관리를 위해 pnpm을 사용하는 환경에서, 의존성 최적화를 위한 pnpm의 내부 로직 변경이 배포 아티팩트의 무결성을 깨뜨린 기술적 결함입니다.

업계에 어떤 영향을 주나?

인프라 자동화와 컨테이너 기반 배포를 사용하는 현대적인 DevOps 환경에서, 빌드 도구의 업데이트가 서비스 가용성에 직접적인 위협이 될 수 있음을 시사합니다.

한국 시장에 어떤 시사점이 있나?

빠른 배포와 효율적인 모노레포 운영을 지향하는 국내 테크 스타트업들은 패키지 매니저 업데이트 시 단순 테스트를 넘어 배포 아티팩트의 구조적 무결성을 검증하는 프로세스가 필요합니다.

이 글에 대한 큐레이터 의견

이번 사례는 개발 도구의 '투명한 업데이트'가 가진 위험성을 극명하게 보여줍니다. 빌드 단계의 성공이 곧 배포의 성공을 보장하지 않는다는 점을 명심해야 합니다. 특히 Docker와 같은 레이어 기반 빌드 환경에서는 빌드 컨텍스트와 최종 이미지 간의 파일 구조 차이가 치명적인 버그를 초래할 수 있습니다.

물론, 패키지 매니저의 성능 최적화와 의존성 관리 로직의 정교화는 장기적으로 개발 생산성을 높이는 필수적인 과정입니다. 하지만 이러한 내부 로직의 변화가 배포 아티팩트의 '독립성(Portability)'을 해친다면, 이는 단순한 버그를 넘어 인프라 신뢰도에 대한 문제입니다. 따라서 스타트업은 패키지 매니저 업데이트 시, 단순 유닛 테스트를 넘어 실제 배포된 이미지의 파일 구조를 `readlink` 등으로 검증하는 '배포 아티팩트 검증 단계'를 CI에 추가하는 전략적 신중함을 갖춰야 합니다.

원문 보기 →