package.json과 npm install의 역할: 첫 install과 이후 install의 차이, resolver와 lock의 역할

npm 패키지 관리의 핵심 개념들인 package.json과 package-lock.json, 그리고 npm install 명령어의 동작 방식을 이해하게 되었습니다. 또한, 의존성 트리, resolver, optional dependencies, peer dependencies 등에 대해서 공부한 과정을 공유합니다.

학습 주제

• 공부 주제: package.json과 npm install의 역할, 의존성 관리 메커니즘
• 대화 제목: "package.json과 npm install의 역할 - 첫 install과 이후 install의 차이, resolver와 lock의 역할, 해야 할 것과 해서는 안되는 것들"
• 학습 날짜: 2026년 3월 1일

질문과 탐구

이번 학습은 package-lock.json에 ^ 기호가 포함되는 이유에 대한 궁금증에서 시작되었습니다. package-lock.json은 정확한 버전을 고정하는 파일임에도 불구하고 왜 버전 범위 표기인 ^가 들어가는지에 대한 질문을 던졌습니다. 이 질문을 통해 npm이 패키지 버전을 관리하는 방식에 대한 탐구를 해보았습니다.

다음과 같은 질문들을 통해 npm의 의존성 관리 메커니즘을 파고들었습니다.

• ^ 기호는 하위 패키지의 허용 버전 범위를 의미하는가?
• optionalDependencies가 설치에 실패해도 에러가 나지 않는 이유는 무엇인가?
• peerDependency는 언제 설치되는가?
• hook이 깨진다는 것은 무엇인가?
• npm install --production 시 무엇이 빠지는가?
• lockfile은 첫 install 시 생성되는가? 이후 install 시에는 어떻게 동작하는가?
• resolver란 무엇이며 어떤 역할을 하는가?
• Python(pip)의 의존성 관리 방식과 npm의 차이는 무엇인가?
• Raspberry Pi(ARM 환경)에서 npm install 시 어떤 바이너리가 설치되는가?
• Docker 빌드 환경과 실제 실행 환경의 아키텍처 차이가 설치에 미치는 영향은 무엇인가?

핵심 학습 내용

1. package.json과 package-lock.json의 역할

• package.json: 프로젝트의 메타데이터와 직접적으로 필요한 패키지들, 그리고 각 패키지의 **허용 버전 범위(semver range)**를 선언하는 파일입니다. 이는 개발자가 프로젝트의 의존성 의도를 명확히 하는 역할을 합니다.
• package-lock.json: npm install 명령어를 통해 실제로 설치된 정확한 버전의 전체 의존성 트리 스냅샷을 기록하는 파일입니다. 이는 프로젝트의 일관성과 재현성을 보장하는 핵심적인 역할을 합니다.

2. ^ 기호와 버전 범위

package-lock.json에 ^ 기호가 보이는 것은 실제 설치된 버전을 의미하는 것이 아니라, 원래 package.json에서 요청했던 허용 범위를 함께 기록하기 때문입니다. 예를 들어, ^5.18.0은 >=5.18.0 <6.0.0의 범위를 의미하며, 이 정보는 의존성 그래프를 재계산할 때 중요한 기준이 됩니다.

3. Resolver의 역할

Resolver는 package.json에 선언된 버전 범위를 바탕으로 실제 설치될 정확한 패키지 버전을 선택하고, 전체 의존성 트리를 계산하여 충돌 없이 배치하는 알고리즘입니다. 이 과정에서 optionalDependencies, peerDependencies, OS/CPU 조건 등 다양한 제약 조건이 고려됩니다.

4. optionalDependencies와 peerDependencies

• optionalDependencies: 해당 패키지가 특정 환경에서 설치되지 않더라도 전체 설치 과정을 중단시키지 않는 의존성입니다. 주로 OS나 CPU 아키텍처에 종속적인 바이너리 패키지들이 이에 해당하며, 설치 실패 시 오류를 발생시키지 않고 조용히 무시됩니다.
• peerDependencies: "나는 이 패키지를 사용하지만, 내가 직접 설치하지는 않는다. 네가 이미 가지고 있어야 한다."는 의미를 가집니다. 이는 React 플러그인처럼 여러 패키지가 동일한 라이브러리(예: React)의 특정 버전을 공유해야 할 때, 중복 설치로 인한 문제를 방지하기 위해 사용됩니다. npm v7부터는 peerDependency가 없을 시 자동 설치를 시도하지만, 근본적으로는 루트 프로젝트에서 관리해야 합니다.

5. npm install vs npm ci

• npm install: package.json을 변경할 때 주로 사용되며, package-lock.json을 참고하지만 필요에 따라 새로운 의존성을 계산하고 package-lock.json을 업데이트할 수 있습니다. 개발 과정에서 유연하게 사용됩니다.
• npm ci: package-lock.json을 절대적으로 기준으로 삼아 설치를 진행합니다. package.json과 package-lock.json이 일치하지 않으면 에러를 발생시키며, node_modules를 항상 새로 설치하여 완벽한 재현성을 보장합니다. CI/CD 환경, 테스트, 배포 단계에서 필수적으로 사용됩니다.

이해한 내용

이번 학습을 통해 package-lock.json이 단순히 버전 고정 파일이 아니라, 프로젝트 의존성 그래프의 완전한 스냅샷이라는 점을 명확히 이해했습니다. ^와 같은 버전 범위 표기는 개발 의도를 나타내는 것이고, 실제 설치되는 버전은 resolver에 의해 결정된 후 package-lock.json에 고정된다는 사실을 알게 되었습니다.

또한, optionalDependencies와 peerDependencies의 존재 이유와 각각의 역할이 명확해졌습니다. 특히 peerDependency가 'hook 깨짐'과 같은 런타임 문제를 방지하는 중요한 메커니즘임을 알게 되었습니다. Python의 pip와 npm의 의존성 관리 방식의 차이점을 비교하며 각 도구의 특징을 더 깊이 이해할 수 있었습니다.

실전 적용

• CI/CD 파이프라인 구축: 테스트 환경으로 사용할 raspiWorker2에서 npm ci를 적극적으로 활용하여 빌드의 재현성과 안정성을 확보할 계획입니다. 개발 단계에서는 npm install로 의존성을 관리하고, 테스트 및 배포 단계에서는 npm ci를 사용하여 환경 오염을 방지할 것입니다.
• 버전 관리 전략: package.json은 새로운 기능 추가 시에만 수정하고, package-lock.json과 node_modules는 npm install 또는 npm ci 명령에 전적으로 맡기는 워크플로를 확립하겠습니다. 이는 의존성 관리의 일관성을 유지하는 데 중요합니다.
• ARM 환경에서의 패키지 설치 이해: Raspberry Pi와 같은 ARM 환경에서 npm install 시, OS 및 CPU 아키텍처에 맞는 바이너리 패키지만 실제로 설치되고 나머지는 optionalDependencies에 의해 조용히 스킵된다는 점을 이해했습니다. 이는 ARM 환경에서 개발하거나 빌드할 때 발생할 수 있는 잠재적 문제를 미리 인지하고 대응하는 데 도움이 될 것입니다.

추가 학습 계획

• SemVer(Semantic Versioning) 규칙 상세 학습: ^, ~ 등 다양한 버전 범위 표기법의 정확한 의미와 작동 방식을 더 깊이 파악하고 싶습니다.
• npm resolver 알고리즘 심층 분석: 의존성 충돌 해결 및 그래프 계산 과정에 대한 알고리즘적 이해를 높이고 싶습니다.
• Hoisting 원리 이해: node_modules 구조가 어떻게 평탄화되는지, hoisting이 성능과 어떤 관련이 있는지 알아보고 싶습니다.

참고 자료

• ChatGPT와의 대화 내용
• esbuild 관련 GitHub 이슈 및 블로그 게시물 (optionalDependencies 및 플랫폼별 바이너리 설치 관련 내용 참고)
• React 공식 문서: peerDependency 및 "Invalid hook call" 에러 관련 내용 학습 참고