초보 개발자가 놓치는 패키지 충돌 확인 방법

웹 프로젝트에서 패키지를 새로 추가하면 의존성 충돌이 생기는 경우가 있다. npm이나 yarn이 경고를 주지만, "일단 설치된다"고 생각하고 넘어가기 쉽다. 하지만 이 충돌이 로컬 개발에서는 우연히 작동하지만, 빌드 후 또는 다른 환경에서는 런타임 에러로 나타날 수 있다.

빌드 시 경고 메시지 확인

패키지 충돌이 있으면, npm install 또는 npm run build를 할 때 이미 경고가 나온다. 그 메시지를 무시하면 안 된다.

npm run build

빌드 출력에서 다음을 주목해야 한다:

• WARN 또는 error로 시작하는 줄들
• "peer dependency"에 대한 경고
• 버전 충돌에 대한 경고

특히 "peer dependency ... not satisfied" 같은 메시지는, 라이브러리가 기대하는 버전의 의존성이 없다는 뜻이다.

로컬과 운영의 설치 환경 차이

로컬 개발 환경에서는 node_modules 폴더가 있을 수 있고, 그 안에 충돌하는 버전들이 우연히 공존하고 있을 수 있다. 하지만 운영 서버의 도커 컨테이너나 CI/CD 파이프라인에서는 깨끗한 상태에서 설치하므로, 충돌이 드러난다.

재현 조건을 만들려면 로컬에서 node_modules를 완전히 제거하고 다시 설치해보자.

rm -rf node_modules package-lock.json
npm install

이렇게 하면 운영 환경과 같은 상태로 설치할 수 있다.

빌드 결과와 실제 런타임 확인

빌드는 성공했더라도, 앱을 실행했을 때 런타임 에러가 나타날 수 있다. 예를 들어:

• 특정 기능을 사용할 때만 에러가 나는 경우 (그 라이브러리를 처음 로드할 때)
• 프로덕션 빌드에서만 에러가 나는 경우
• 서버 환경에서만 에러가 나는 경우

로컬에서 프로덕션처럼 빌드하고 실행해서 에러가 나는지 확인해야 한다.

npm run build
npm run start

실행 후 브라우저 콘솔과 서버 로그에서 에러 메시지를 찾자.

설정 파일 확인: package.json의 의존성 버전

package.json의 의존성 버전을 명확히 해야 한다:

• "react": "^18.0.0" — 18.0.0 이상 19.0.0 미만
• "react": "~18.2.0" — 18.2.0 이상 18.3.0 미만
• "react": "18.2.0" — 정확히 18.2.0만

특정 라이브러리가 React 18을 필요로 하는데, package.json에는 React 17로 지정되어 있으면 충돌한다.

실수하기 쉬운 부분

가장 흔한 실수들:

1. 경고를 무시하기: npm의 경고는 대부분 실제 문제의 신호다
2. 로컬과 운영의 설치 방식이 다르다: 로컬에서는 npm install을 여러 번 해서 의존성이 섞여 있을 수 있다
3. monorepo에서 버전 불일치: 같은 패키지가 다른 버전으로 설치되어 있을 수 있다
4. lockfile을 commit하지 않기: package-lock.json을 무시하면 팀원마다 다른 버전이 설치된다

의심이 들면 npm ls PACKAGE_NAME으로 그 패키지의 모든 버전을 확인할 수 있다.