이전 포스팅과 관련해서 같은 레포인데 Ubuntu 로컬 머신에서만 pnpm install이 실패하는 문제가 있었습니다.
로그를 아무리 봐도 모호한 스택 트레이스만 보였고, CI나 macOS에서는 멀쩡히 돌아가서 디버깅 하는 데에 시간을 너무 많이 허비했기에
환경에 따라 pnpm 설치가 실패하는 이유를 알아내고, 정확히 로깅할 수 있도록 작업해보았습니다.
검색과 여러 이슈 트래킹을 해보니, Node 버전이 pnpm 최소 요구사항보다 낮아서 문제가 발생했다는 걸 알게 되었던 것이고,
특히 회사에서 발생한 문제였기 때문에 저뿐만 아니라 다른 팀원 분들도 문제 없이 사용할 수 있도록 명확하게 에러를 내보내려고 작업하였습니다.
🧭 원인 가설: Node 버전 불일치
검색과 내부 이슈 트래킹 끝에, 원인은 Node 버전이 pnpm 최소 요구사항보다 낮았던 것이라는 가설에 도달했습니다.
하지만 당시에는 에러 메시지가 모호해, 이걸 직접 확인할 방법이 필요했습니다.
🔍 재현 및 검증: nvm으로 Node 버전 낮추기
1. Node 버전 강제로 다운
nvm install 17.5.0
nvm use 17.5.0
node -v # v17.5.02. 낮은 Node에서 pnpm 실행
• 변경 전: 내부 모듈에서 알 수 없는 에러 발생 → 원인 추적 어려움
• 변경 후(engines 추가): **“Node 버전이 낮다”**는 명확한 오류 메시지 출력// package.json
{
"engines": {
"node": ">=18.12.0",
"pnpm": ">=10"
}
}package.json의 engines에 최소 node 버전(pnpm이 동작하는 최소 버전)을 추가하고 난 후 버전이 낮은 node 환경에서 pnpm을 사용해본 결과,
아래와 같이 버전의 문제라는 오류가 노출되는 것을 확인할 수 있었습니다!
기존보다 확실히 에러 메시지가 명확하게 수정되는 것을 확인할 수 있습니다.
3. 테스트 종료 후 원복
nvm deactivate
nvm uninstall 17.5.0
node -v # v22.13.1🛠️ 그래서 왜 engines가 중요했냐면,,,
기본적으로 팀원/CI 환경마다 Node 버전이 모두 다를 수 있습니다.
그리고 pnpm은 Node 기능을 많이 쓰다 보니, 최소 버전 미만이면 내부에서 애매한 에러가 터지게 되더라고요,,
이를 해결하기 위해 package.json에 engines를 선언해두면, 아예 설치 초반에 “버전이 안 맞다” 하고 막아주니까 원인을 찾기가 훨씬 쉬워졌습니다.
추가로 .nvmrc 파일을 두면 팀 내 권장 Node 버전도 공유하기 편리해집니다.
# .nvmrc
18.20.4📝 결국 버전 불일치 문제,,, 로깅까지 추가해두기
Ubuntu 로컬에서만 pnpm이 실패한 이유는 결국 Node 버전 불일치였습니다.
버전 불일치 때문이 맞는지 확신이 들지 않는 상황에서 직접 nvm으로 버전을 내려보았고, 실제로 맞다는 것을 알게 되었습니다.
그래서 package.json에 engines를 선언해두니, 이제는 낮은 버전 환경에서 바로 에러가 나서 원인을 확인할 수 있었습니다.
개인적으로 애매한 에러 로그 대신에 “Node 버전 문제”라는 정확한 가이드가 나오니까, 팀 단위 개발 환경에서도 혼란을 줄일 수 있게 되어서 꼭 필요한 작업이라는 생각이 들었습니다.
