📦 npm 멘탈 모델 — 레지스트리, 패키지, 모듈을 꿰뚫어라

📋 목차

• 📌 이 문서를 읽기 전에
• 🤔 왜 알아야 하는가
• 🌐 npm 의 세 가지 얼굴
• 📦 패키지 vs 모듈
• 🔍 스코프 패키지
• ⚙️ npm install 이 실제로 하는 일
• 💾 npm 캐시
• 🚨 자주 마주치는 npm 에러 해결
• 🏁 이번에 배운 내용 총정리
• 📝 마무리 퀴즈
• 🐣 영철이의 퇴근 일기
• 🔗 더 알아보기

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 15분(전체) / 핵심 파트만: 7분

🗺️ 이 문서의 흐름
npm 의 정체 파악 → 레지스트리 동작 원리 → 패키지 vs 모듈 구분 → install 내부 과정 → 캐시 원리 → 에러 해결

🎯 이 문서를 다 읽으면 할 수 있는 것

• npm 이 CLI / 레지스트리 / 웹사이트 세 가지 역할을 한다는 것을 설명할 수 있다
• 패키지와 모듈의 차이를 정확히 구분할 수 있다
• @org/package 형태의 스코프 패키지가 왜 쓰이는지 이해한다
• npm install 이 내부적으로 HTTP 요청 → tarball 다운 → 캐시 → 압축 해제 순으로 동작함을 설명할 수 있다
• EACCES, ENOENT, ERESOLVE 에러를 보고 원인을 바로 파악할 수 있다

🗺️ 이 문서의 배경 세계관: '영수네 커뮤니티'

• 🐣 영철 ( 신입 ): "리드 님, 저 오늘 npm install 했는데 ERESOLVE unable to resolve dependency tree 라고 엄청난 에러가 났어요. 구글링해도 무슨 말인지 모르겠고... 그냥 --legacy-peer-deps 붙이면 된다고 해서 붙였는데 그게 맞는 건가요? 아 그리고 @youngsoo/ui 같이 골뱅이 붙은 패키지는 뭔가요? 일반 패키지랑 다른 건가요?"
• 🦁 영호 ( 리드 ): "영철 님, --legacy-peer-deps 는 에러를 해결한 게 아니라 덮어씌운 거예요. 의존성 충돌이 있다는 경고를 무시하겠다는 선언이에요. 근본적으로 npm 이 뭘 하는지부터 이해해야 이런 에러를 진짜로 해결할 수 있어요. @youngsoo/ui 는 스코프 패키지인데, 이것도 원리를 알면 왜 이 형태를 쓰는지 바로 납득이 가요."

🤔 왜 알아야 하는가

영수네 커뮤니티 팀에 영철이가 합류한 첫 날. 설레는 마음으로 프로젝트를 클론하고 npm install 을 실행했다. 그런데 터미널이 빨간 에러로 가득 찼다.

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! peer dep missing: react@"^17.0.0", required by some-legacy-ui@3.0.0

영철이는 구글링 끝에 --legacy-peer-deps 를 붙이면 해결된다는 글을 발견하고 그대로 실행했다. 설치는 됐지만, 다음 날 QA 에서 이상한 버그가 발견됐다. 리액트 컨텍스트 값이 UI 라이브러리 안에서 전달이 안 되는 현상이었다.

범인은 --legacy-peer-deps 였다. 이 옵션은 peer dependency 충돌을 "무시"하는 것인데, 결과적으로 두 가지 버전의 React 가 공존하게 되어 Context 가 제대로 연결되지 않았던 것이다.

npm 이 어떻게 동작하는지 원리를 이해하면, 이런 에러가 왜 발생하는지, 그리고 어떻게 진짜로 해결하는지가 보인다.

🌐 npm 의 세 가지 얼굴

많은 개발자가 "npm = npm install 치는 도구" 로만 알고 있다. 하지만 npm 은 정확히 세 가지 역할을 동시에 한다.

1. 웹사이트 (npmjs.com)

패키지를 검색하고, 문서를 보고, 다운로드 통계를 확인하는 포털.

https://www.npmjs.com/package/react  ← 여기서 패키지 정보 확인

2. 레지스트리 (Registry)

전 세계 npm 패키지들이 저장된 거대한 데이터베이스이자 HTTP 서버. 오늘 기준 약 200만 개 이상의 패키지가 등록되어 있다.

https://registry.npmjs.org/react        ← 패키지 메타데이터 (JSON)
https://registry.npmjs.org/react/-/react-18.2.0.tgz  ← 실제 코드 파일 (tarball)

3. CLI (명령줄 도구)

우리가 터미널에서 입력하는 npm install, npm run build, npm publish 등의 명령어 도구.

npm install react      # 레지스트리에서 react 를 받아 node_modules 에 설치
npm run build          # package.json 의 scripts.build 실행
npm publish            # 내 패키지를 레지스트리에 업로드

🦁 영호의 인사이트: "npm 레지스트리는 결국 HTTP API 서버예요. curl https://registry.npmjs.org/react 를 실행해보면 react 의 모든 버전 정보가 JSON 으로 쭉 나와요. CLI 는 이 API 를 호출해서 필요한 정보와 파일을 받아오는 클라이언트예요."

📦 패키지 vs 모듈 — 헷갈리기 쉬운 두 개념

패키지 (Package) = package.json 이 있는 폴더 (또는 그걸 압축한 tarball)
모듈  (Module)  = Node.js 에서 require() / import 로 불러올 수 있는 것

패키지이면서 모듈인 경우 (가장 흔한 케이스)

node_modules/
  react/               ← package.json 있음 (패키지) + import 가능 (모듈)
    package.json
    index.js
    jsx-runtime.js

모듈이지만 패키지가 아닌 경우

// src/utils/formatDate.ts
// package.json 없음 → 패키지 아님, 그러나 import 가능하므로 모듈
export const formatDate = (date: Date): string => { ... }

패키지이지만 모듈이 아닌 경우

node_modules/
  some-cli-tool/       ← package.json 있음 (패키지)
    package.json
    bin/
      cli.js           ← 하지만 require() 로 불러 쓰는 용도가 아님

💡 핵심: 모든 npm 패키지가 모듈은 아니다. CLI 도구처럼 설치는 되지만 코드에서 직접 import 하지 않는 패키지들이 있다. 이 구분은 peerDependencies 를 이해하는 데 중요한 기반이 된다.

🔍 스코프 패키지 — @org/package 의 의미

npm install @types/react       # @types 스코프
npm install @tanstack/react-query  # @tanstack 스코프
npm install @youngsoo/ui       # 영수네 팀 내부 스코프

스코프 패키지의 형태: @스코프명/패키지명

왜 스코프를 쓰는가?

1. 이름 충돌 방지

react-query        ← 누군가 이미 점유 중일 수 있음
@tanstack/react-query  ← @tanstack 스코프 아래에서 고유하게 존재

2. 접근 제어 (공개 vs 비공개)

# 공개 스코프 패키지 — 누구나 설치 가능
npm install @types/react
 
# 비공개 스코프 패키지 — 인증된 팀원만 설치 가능
npm install @youngsoo/ui   # 내부 private 레지스트리에서 가져옴

3. 영수네 팀 내부 패키지 운용

# .npmrc 에 내부 레지스트리 설정
@youngsoo:registry=https://npm.youngsoo.internal.com/

// package.json
// 💡 @ 기호(스코프)가 붙어 있으면 npm은 "아, 이건 특정 조직(org) 소속 패키지구나" 하고 깨닫습니다.
// .npmrc 에 설정해 둔 대로 레지스트리를 분기 처리하게 됩니다.
{
  "dependencies": {
    // 🦁 우리 팀 내부 저장소(npm.youngsoo.internal.com)에서만 받을 수 있는 시크릿 패키지들!
    "@youngsoo/ui": "^1.0.0",       
    "@youngsoo/utils": "^2.0.0",    
    // 🌐 이건 골뱅이가 없으니 공식 npm 레지스트리(기본값)에서 다운로드합니다.
    "react": "^18.2.0"              
  }
}

🐣 영철: "아, 그러면 @types/react 는 TypeScript 팀이 올린 공식 타입 패키지고, @youngsoo/ui 는 우리 팀이 올린 내부 패키지네요?"

🦁 영호: "정확해요. @types 는 DefinitelyTyped 라는 오픈소스 커뮤니티가 관리하는 공개 스코프예요. 누가 스코프를 만드느냐에 따라 공개/비공개, 내부/외부가 결정돼요."

⚙️ npm install 이 실제로 하는 일

npm install react 한 줄이 실행될 때 내부적으로 일어나는 과정:

① package.json 파싱
   └─ "react": "^18.2.0" 확인

② 레지스트리에 메타데이터 요청 (HTTP GET)
   └─ GET https://registry.npmjs.org/react
   └─ 응답: 모든 버전 목록, 의존성 트리, dist 정보

③ 버전 Resolution (^18.2.0 범위에서 최신 버전 선택)
   └─ 결정: react@18.2.0

④ 의존성 트리 계산
   └─ react@18.2.0 이 필요로 하는 것: loose-envify, scheduler...
   └─ 재귀적으로 의존성의 의존성까지 계산

⑤ tarball 다운로드 (캐시 확인 먼저)
   └─ GET https://registry.npmjs.org/react/-/react-18.2.0.tgz
   └─ ~/.npm 캐시에 저장

⑥ node_modules/ 에 압축 해제

⑦ package-lock.json 갱신

의존성 트리가 복잡한 이유

react 설치 요청
  └─ react@18.2.0
       ├─ loose-envify@1.4.0
       │    └─ js-tokens@4.0.0
       └─ scheduler@0.23.0

react 하나를 설치해도 실제로는 여러 패키지가 함께 설치된다. npm 은 이 모든 의존성의 의존성까지 재귀적으로 탐색해서 설치한다.

🔥 ERESOLVE 에러의 진짜 원인: 의존성 트리를 계산하다가 서로 양립 불가능한 버전 요구사항이 충돌할 때 발생한다. 예를 들어 라이브러리 A 는 react@^17 을 요구하고, 내 앱은 react@18 을 쓰는 경우다. --legacy-peer-deps 는 이 충돌을 무시하고 강행하는 옵션으로, 충돌이 런타임 버그로 이어질 수 있다.

💾 npm 캐시 — 두 번째 install 이 빠른 이유

npm 은 한 번 다운로드한 패키지를 로컬 캐시에 저장한다.

~/.npm/                          # 캐시 디렉터리 (기본값)
  _cacache/
    content-v2/
      sha512/                    # tarball 을 SHA512 해시로 저장
        a1/b2/c3.../

npm cache verify      # 캐시 무결성 검사
npm cache clean --force  # 캐시 전체 삭제 (이상할 때만 씀)

CI 환경에서 캐시 활용:

# 💡 GitHub Actions 에서 Node.js 패키지 설치 시간을 혁신적으로 단축하는 마법의 주문입니다.
 
- name: Cache npm
  uses: actions/cache@v3
  with:
    # 🦁 npm이 패키지(tarball)를 캐싱해두는 바로 그 폴더를 통째로 깃허브 서버 안에 저장해라!
    path: ~/.npm
    
    # 캐시를 찾을 때 쓸 고유 열쇠 (lock 파일 내용이 변하면 이 열쇠 모양도 바뀜 -> 새로 받아야 함)
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-
 
- name: Install dependencies
  # 💡 npm install 대신 npm ci 를 쓰면 캐시를 엄청 빠르게 읽어와서 node_modules 에 풀어버립니다.
  run: npm ci

package-lock.json 의 해시를 캐시 키로 사용하면, lock 파일이 변경될 때만 캐시가 무효화되어 CI 속도를 크게 향상시킬 수 있다.

🚨 자주 마주치는 npm 에러 해결

EACCES — 권한 에러

npm ERR! code EACCES
npm ERR! syscall mkdir
npm ERR! path /usr/local/lib/node_modules

원인: 전역 설치(-g) 시 루트 권한이 필요한 경로에 쓰려고 할 때.

해결:

# ❌ 절대 이렇게 하지 마라 — 보안 위험
sudo npm install -g some-package
 
# ✅ nvm 으로 Node.js 를 설치하면 권한 문제가 없음
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 18
nvm use 18
npm install -g some-package   # 권한 문제 없음

ERESOLVE — 의존성 충돌

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree

원인: 서로 호환되지 않는 버전 요구사항 충돌.

해결 순서:

# 1단계: 어떤 패키지가 충돌하는지 파악
npm install --verbose 2>&1 | grep "ERESOLVE"
 
# 2단계: overrides 로 버전 강제 통일 (package.json)
# (4장 의존성 편에서 상세 설명)
 
# 3단계: 정말 부득이할 때만 legacy-peer-deps 사용
npm install --legacy-peer-deps

ENOENT — 파일을 못 찾을 때

npm ERR! code ENOENT
npm ERR! syscall open
npm ERR! path /path/to/package.json

원인: 현재 디렉터리에 package.json 이 없는 경우.

# 올바른 디렉터리인지 확인
ls package.json
 
# 없다면 초기화
npm init -y

ENOTFOUND — 레지스트리 연결 실패

npm ERR! code ENOTFOUND
npm ERR! errno ENOTFOUND
npm ERR! network request to https://registry.npmjs.org/... failed

원인: 네트워크 문제 또는 잘못된 레지스트리 설정.

# 레지스트리 설정 확인
npm config get registry
 
# 기본값으로 초기화
npm config set registry https://registry.npmjs.org/

🏁 이번에 배운 내용 총정리

📝 마무리 퀴즈

Q1. npm 레지스트리에 대한 설명으로 올바른 것은?

a) npm CLI 와 동일한 개념으로, 설치 명령을 처리하는 도구다
b) 패키지의 소스코드와 메타데이터를 저장하는 HTTP 서버다
c) node_modules 폴더와 동일한 개념이다
d) 로컬 컴퓨터에 설치되는 데이터베이스다

✅ 정답: b — 패키지의 소스코드와 메타데이터를 저장하는 HTTP 서버다

💡 상세 해설:

• 원리 설명: npm 레지스트리는 https://registry.npmjs.org 에서 동작하는 HTTP API 서버다. curl https://registry.npmjs.org/react 를 실행하면 react 의 모든 버전 정보가 JSON 으로 응답된다. CLI 는 이 서버에 요청을 보내서 패키지를 받아온다.
• 오답 피드백: a — CLI 와 레지스트리는 완전히 다른 개념이다. CLI 는 클라이언트, 레지스트리는 서버다. c — node_modules 는 내 컴퓨터에 설치된 패키지들의 물리적 폴더다. d — 레지스트리는 원격 서버다.
• 📌 핵심 기억법: "npm CLI 는 레지스트리라는 원격 서버의 클라이언트다."

Q2. 아래 에러가 발생하는 근본 원인은 무엇인가?

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! peer dep missing: react@"^17.0.0", required by some-legacy-ui@2.0.0

a) npm 이 인터넷에 연결되지 않아 패키지를 다운로드할 수 없다
b) some-legacy-ui@2.0.0 이 요구하는 React 17 과 현재 프로젝트의 React 18 이 충돌한다
c) package.json 파일이 손상되었다
d) npm 버전이 낮아서 최신 패키지를 설치할 수 없다

✅ 정답: b — 버전 요구사항 충돌

💡 상세 해설:

• 원리 설명: some-legacy-ui@2.0.0 의 peerDependencies 에 "react": "^17.0.0" 이 선언되어 있는데, 현재 프로젝트가 react@18.x 를 사용하고 있어 npm 이 의존성 트리를 해결하지 못한다. npm v7+ 는 이런 충돌을 기본적으로 에러로 처리한다.
• 올바른 해결 방법: some-legacy-ui 의 최신 버전으로 업그레이드하거나, 해당 라이브러리를 React 18 을 지원하는 대안으로 교체한다. --legacy-peer-deps 는 충돌을 숨길 뿐 해결하지 않는다.
• 📌 핵심 기억법: "ERESOLVE = 의존성 버전 계약이 서로 맞지 않는 충돌."

Q3. 🐣 영철이의 테스트 타임 — 시니어 면접 도전

영철이가 시니어 포지션 면접을 보러 갔다. 면접관이 물었다. "개발자가 npm install some-package 를 실행했을 때, 그 패키지의 코드가 node_modules 에 들어가기까지 내부적으로 어떤 과정을 거치나요? 최대한 상세하게 설명해주세요."

영철이의 답변:

"레지스트리에서 파일을 받아서 node_modules 에 넣어요."

면접관 (영호 스타일)이 추가 질문했다. "그 사이에 캐시, 버전 결정, 의존성 트리 계산 같은 과정이 있지 않나요?"

올바른 완전한 답변은 무엇인가?

✅ 정답: 6단계 과정 — 메타데이터 요청 → 버전 결정 → 의존성 트리 → tarball 다운(캐시 확인) → 압축 해제 → lock 파일 갱신

💡 상세 해설:

• 1단계 (메타데이터 요청): CLI 가 https://registry.npmjs.org/<패키지명> 에 GET 요청을 보내 패키지의 모든 버전 목록과 각 버전의 의존성 정보를 받는다.
• 2단계 (버전 결정): package.json 에 명시된 버전 범위(예: ^4.7.0) 에 맞는 가장 높은 버전을 선택한다.
• 3단계 (의존성 트리 계산): 설치할 패키지가 필요로 하는 패키지들을 재귀적으로 파악하여 전체 설치 목록을 계산한다.
• 4단계 (tarball 다운로드): ~/.npm 캐시를 먼저 확인하고, 없으면 레지스트리에서 .tgz 파일을 다운로드하여 캐시에 저장한다.
• 5단계 (압축 해제): tarball 을 node_modules/ 에 압축 해제한다.
• 6단계 (lock 파일 갱신): package-lock.json 에 설치된 정확한 버전과 tarball 의 무결성 해시(sha512)를 기록한다.
• 📌 핵심 기억법: "레지스트리는 서버고, CLI 는 그 서버에서 파일을 받아오는 정교한 클라이언트다. 단순 다운로드가 아니라 버전 계산 + 캐시 + 무결성 검증이 모두 포함된다."

🐣 영철이의 퇴근 일기

퇴근하면서 에어팟 꽂고 걷는 중인데, 오늘 하루가 꽤 꽉 찬 느낌이다.

솔직히 말하면 오늘 아침까지만 해도 npm 은 그냥 "설치 버튼" 이었다. --legacy-peer-deps 붙였을 때 왜 버그가 났는지도 몰랐고. 근데 지금은 안다. 두 개의 React 인스턴스가 생겨서 Context 가 끊겼던 거였다. npm 이 내부에서 의존성 트리를 계산하고 버전을 조율하고 있다는 걸 몰랐으니 당연히 원인을 못 찾을 수밖에.

💡 오늘의 교훈: "--legacy-peer-deps 는 에러를 해결하는 게 아니라 눈을 가리는 것이다. 진짜 해결은 충돌의 원인을 아는 것에서 시작한다."

그리고 @youngsoo/ui 가 스코프 패키지라는 것도 이제 제대로 알았다. 팀 내부 레지스트리에서 가져오는 거였구나. 생각보다 npm 생태계가 훨씬 넓었다.

집에 가서 뭐 먹을까. 오늘은 편의점 도시락 정도면 충분할 것 같다. 내일은 package.json 필드들을 제대로 파봐야지. 영호 리드 님이 다음에는 package.json 을 해부한다고 하셨으니까.

🔗 더 알아보기

• npm 공식 문서 — About npm
• npm 공식 문서 — About packages and modules
• npm 공식 문서 — About scopes
• npm 공식 문서 — npm cache