1. npm 의존성 버전 충돌 현상
프로젝트가 직접 또는 간접적으로 동일한 패키지(lodash, react 등)의 호환되지 않는 여러 버전을 의존할 때 발생하는 문제입니다. npm은 이러한 의존성을 자동으로 해결하려 하지만, 일부 경우 적절한 버전을 선택하지 못해 실행 시 예상치 못한 오류가 발생할 수 있습니다.
2. 의존성 충돌 발생 원인
- 패키지 A는 C@1.0.0, 패키지 B는 C@2.0.0을 의존하는 경우
- 버전 범위(^1.2.3, ~1.2.3)를 사용해 정확한 버전을 지정하지 않은 경우
- 다중 중첩된 의존성 트리 구조가 복잡한 경우
- package-lock.json과 같은 의존성 잠금 파일을 사용하지 않은 경우
3. 의존성 충돌 확인 방법
npm ls 명령어 활용
npm ls lodash
npm ls결과 예시:
├── lodash@4.17.21
└─┬ some-package
└── lodash@3.10.1npm dedupe 명령어 적용
npm dedupe의존성 트리를 최소화하여 중복 설치를 줄이는 기능입니다. 하지만 서로 호환되지 않는 실제 버전 차이가 있을 경우 효과가 제한적입니다.
4. 의존성 충돌 해결 전략
직접 의존성 조정
- npm ls 명령으로 충돌 패키지 확인
- 의존성 트리를 분석해 충돌 원인 파악
- 의존 패키지 버전을 조정하거나 대체 패키지를 선택
resolutions 필드 활용 (Yarn/pnpm 전용)
"resolutions": {
"lodash": "4.17.21",
"react": "18.2.0"
}npm-force-resolutions 도구 활용
npm install npm-force-resolutions --save-dev
// package.json에 resolutions 추가
"scripts": {
"preinstall": "npx npm-force-resolutions"
}5. 의존성 충돌 방지 방법
- package-lock.json 파일을 버전 관리에 포함
- 핵심 의존성에는 고정 버전을 명시
- npm outdated 명령으로 주기적인 업데이트 수행
- depcheck, npm-check-updates 등 의존성 분석 도구 활용
6. npm 기본 개념
Node.js 공식 패키지 관리 도구로, 프로젝트 의존성 관리, 패키지 설치/업데이트, 스크립트 실행 등의 핵심 기능을 제공합니다.
7. npm, yarn, pnpm 비교
| 특징 | npm | yarn | pnpm |
|---|---|---|---|
| 설치 방식 | 중첩 구조 | 플랫 구조 | 하드링크 기반 |
| 속도 | 보통 | 빠름 | 최적화됨 |
| 의존성 일관성 | package-lock.json | yarn.lock | pnpm-lock.yaml |
8. 주요 npm 명령어
| 명령 | 설명 |
|---|---|
| npm install | 의존성 설치 |
| npm ci | CI 환경용 정확한 설치 |
| npm update | 패키지 업데이트 |
| npm run | 스크립트 실행 |
9. dependencies vs devDependencies
| 타입 | 설명 | 사용 사례 |
|---|---|---|
| dependencies | 운영 환경 필요 | react, express |
| devDependencies | 개발 환경 전용 | eslint, jest |
10. 패키지 출판 절차
- npm 계정 생성
- npm init으로 프로젝트 초기화
- npm publish 명령으로 배포
- 버전 관리(semantic versioning) 준수
11. 설치 문제 해결 팁
- 국내 미러 사용:
npm config set registry https://registry.npmmirror.com - node_modules 삭제 후 재설치
- npm cache clean 명령 활용