📥 npm install 완전 해부 — lock 파일, node_modules, npm ci

📋 목차

• 📌 이 문서를 읽기 전에
• 🤔 왜 알아야 하는가
• 🔒 package-lock.json 의 구조와 역할
• ⚖️ npm install vs npm ci
• 🌳 node_modules 의 구조
• 👻 팬텀 의존성
• 🧹 node_modules 관리 명령어
• ⚙️ .npmrc 로 install 동작 제어
• 🏁 이번에 배운 내용 총정리
• 📝 마무리 퀴즈
• 🐣 영철이의 퇴근 일기
• 🔗 더 알아보기

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 20분(전체) / 핵심 파트만: 8분 (lock 파일 + npm ci)

🗺️ 이 문서의 흐름
lock 파일 구조 이해 → npm install vs npm ci → node_modules 호이스팅 → 팬텀 의존성 함정 → .npmrc 설정

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

• package-lock.json 의 내부 구조를 읽고 integrity 필드가 무엇을 보장하는지 설명할 수 있다
• npm install 과 npm ci 의 결정적 차이를 상황에 맞게 선택해 사용할 수 있다
• node_modules 의 플랫 구조와 호이스팅 원리를 이해한다
• 팬텀 의존성이 무엇이고 왜 위험한지 설명할 수 있다
• .npmrc 로 engine-strict, save-exact 등을 설정할 수 있다

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

• 🐣 영철 ( 신입 ): "리드 님, CI 에서 계속 빌드가 실패해요. 로컬에서는 완벽한데... GitHub Actions 로그 보니까 npm install 할 때마다 버전이 조금씩 달라지는 것 같아요. 그리고 package-lock.json 이 엄청 길어서 뭔 내용인지 모르겠어요. 읽어야 하나요? 그냥 자동 생성이니까 신경 안 써도 되는 거 아닌가요?"
• 🦁 영호 ( 리드 ): "영철 님, CI 에서 npm install 대신 npm ci 를 써야 해요. npm install 은 lock 파일을 갱신할 수 있어서 매 빌드마다 조금씩 달라질 수 있거든요. package-lock.json 은 읽을 필요는 없지만, 이게 어떤 역할을 하는지 알아야 왜 CI 에서 npm ci 를 써야 하는지 이해할 수 있어요."

🤔 왜 알아야 하는가

"제 로컬에서는 되는데 CI 에서만 안 돼요" — 개발자 세계에서 가장 고통스러운 문장 중 하나다.

영수네 팀이 배포 전날 밤에 이 상황을 만났다. 영철이 로컬에서는 빌드가 완벽한데, GitHub Actions 에서는 계속 타입 에러가 났다. 원인을 찾아보니 로컬의 typescript@5.2.0 과 CI 의 typescript@5.3.3 이 달랐다. CI 에서 npm install 을 실행할 때마다 lock 파일이 없어서 그때그때 최신 버전을 가져왔던 것이다.

package-lock.json 과 npm ci 를 제대로 이해하면 이런 일은 절대 일어나지 않는다.

🔒 package-lock.json 의 구조와 역할

핵심 역할 — 재현 가능한 빌드 보장

package.json     = "의도" — react@^18.2.0 범위면 됨
package-lock.json = "공증" — 오늘 18.2.0 을 설치했고, 이 tarball 의 해시값은 xxx 임

lock 파일의 실제 구조

{
  "name": "youngsoo-community",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "youngsoo-community",
      "version": "1.0.0",
      "dependencies": {
        "react": "^18.2.0"
      }
    },
    // 💡 node_modules 안에 실제로 어떤 파일이 들어갔느냐! 하는 실물 장부입니다.
    "node_modules/react": {
      "version": "18.2.0", // 🦁 ^18.2.0 범위 중에서 "정확히 이 버전"을 깔았다고 명시합니다.
      "resolved": "https://registry.npmjs.org/react/-/react-18.2.0.tgz",
      // [초핵심] 이 파일의 지문(해시값)입니다. 파일이 1바이트라도 다르면 여기서 걸러집니다.
      "integrity": "sha512-/3IjMdb2L9QbBdWiW5e3P2/npwMBaU9mHCSCUzNln0ZCYbcfTsGbTJrU/kGemdH2IWmB2ioZ+zkxtmq6g09fA==",
      "engines": {
        "node": ">=0.10.0"
      }
    }
  }
}

🔐 integrity 의 역할: 악의적인 공격자가 npm 레지스트리를 조작해 다른 코드를 주입하더라도, integrity 해시가 일치하지 않으면 npm 이 설치를 거부한다. 이것이 공급망 공격(supply chain attack) 을 막는 첫 번째 방어선이다.

lock 파일 버전 호환성

팀원 중 npm 버전이 다르면 lock 파일이 계속 변경될 수 있다. .npmrc 로 npm 버전을 통일하거나 engines 에 "npm": ">=9.0.0" 을 명시한다.

절대 규칙

✅ package-lock.json  → 반드시 git 커밋
❌ node_modules/      → 반드시 .gitignore 추가

# .gitignore
node_modules/
.next/

⚖️ npm install vs npm ci — 결정적 차이

npm install

npm install

• package.json 기준으로 동작
• 허용 버전 범위 내에서 최신 버전 선택 가능
• package-lock.json 을 갱신할 수 있음
• 기존 node_modules 를 재사용 (속도 우선)
• 사용 시점: 개발 중 새 패키지를 추가하거나, 버전을 올릴 때

npm ci

npm ci

• package-lock.json 기준으로 동작 (정확한 버전만)
• package-lock.json 을 절대 갱신하지 않음 (lock 없으면 에러)
• 기존 node_modules 를 삭제 후 처음부터 설치
• 더 엄격하고 예측 가능한 설치
• 사용 시점: CI/CD 환경, Docker 이미지 빌드, 프로덕션 배포

              npm install          npm ci
기준 파일    package.json         package-lock.json
lock 변경    가능                 불가 (에러 발생)
lock 없으면  새로 생성            에러로 종료
node_modules 재사용              삭제 후 재설치
속도         보통                 빠름 (초기화 후 캐시 사용 시)
안정성       낮음                 높음

🔥 실무 황금 규칙:

• 로컬 개발: npm install
• CI/CD: 무조건 npm ci
• Docker Dockerfile: RUN npm ci --omit=dev

# ✅ GitHub Actions 올바른 설정: 'npm install'은 절대 금지! 'npm ci'가 정답입니다.
- name: Install dependencies
  run: npm ci     
 
# ✅ Dockerfile 올바른 설정: 프로덕션 이미지에는 용량 다이어트를 위해 devDependencies를 뺍니다.
RUN npm ci --omit=dev    

🌳 node_modules 의 구조 — 호이스팅과 중첩

npm v3+ 의 플랫(Flat) 구조

npm v2 이하에서는 모든 의존성이 중첩 구조로 설치됐다:

# npm v2 (구버전 — 중첩 구조)
node_modules/
  react-dom/
    node_modules/
      react/          ← react-dom 의 react
  next/
    node_modules/
      react/          ← next 의 react (중복!)
      react-dom/      ← next 의 react-dom (중복!)

중복이 너무 많아 node_modules 크기가 폭발적으로 커졌다.

npm v3+ 는 호이스팅(Hoisting) 으로 이를 해결한다:

# npm v3+ (플랫 구조 — 호이스팅)
node_modules/
  react/              ← 최상위로 올라옴 (호이스팅)
  react-dom/          ← 최상위로 올라옴
  next/               ← react 없음, 상위 react 공유
  some-lib/           ← react 없음, 상위 react 공유

모든 패키지가 react@18.2.0 을 요구하면 최상위에 하나만 놓고 모두 공유한다.

버전이 다를 때 — 중첩이 발생하는 경우

node_modules/
  react/               ← v18.2.0 (호이스팅)
  old-library/
    node_modules/
      react/           ← v16.14.0 (old-library 가 16 버전 요구)

old-library 가 React 16 을 요구하고 메인 앱은 React 18 을 쓰면, 두 버전이 공존한다. 이것이 node_modules 크기가 커지고 peerDependencies 충돌이 생기는 원인이다.

👻 팬텀 의존성 — 설치한 적 없는데 쓸 수 있는 이유와 함정

호이스팅의 부작용으로 팬텀 의존성(Phantom Dependency) 이 생긴다.

// 내 package.json
{
  "dependencies": {
    "next": "^14.1.0"
  }
}

// 내 코드 — 직접 설치하지 않은 lodash 를 import!
import merge from 'lodash/merge'   // ← 팬텀 의존성

next 가 내부적으로 lodash 를 사용하기 때문에, node_modules/lodash 가 호이스팅으로 최상위에 존재한다. 내가 설치한 적 없어도 import 가 동작한다.

왜 이게 위험한가?

오늘: next@14.1.0 이 lodash@4.17.21 을 사용 → 내 코드에서 쓸 수 있음
미래: next@14.2.0 이 lodash 의존성 제거 → 내 코드가 갑자기 에러

내가 아무것도 바꾸지 않았는데 서비스가 망가짐

해결: 직접 사용하는 패키지는 반드시 명시적으로 설치한다.

npm install lodash    # 직접 설치

// package.json 에 명시됨
{
  "dependencies": {
    "lodash": "^4.17.21",
    "next": "^14.1.0"
  }
}

💡 pnpm 이 이 문제를 해결하는 방식: pnpm 은 하드링크 + 심볼릭 링크 구조로 팬텀 의존성을 원천 차단한다. 명시적으로 설치하지 않은 패키지는 import 자체가 에러난다. 대규모 모노레포에서 pnpm 이 선호되는 이유 중 하나다.

🧹 node_modules 관리 명령어

# 중복 의존성 정리
npm dedupe              # 중복 패키지를 제거하고 공유 가능한 것은 호이스팅
 
# 현재 설치된 패키지 목록
npm list                # 전체 트리
npm list --depth=0      # 직접 의존성만
npm list react          # 특정 패키지 버전 확인
 
# 쓸모없는 패키지 정리 (package.json 에 없는 것 제거)
npm prune               # 불필요 패키지 삭제
npm prune --production  # devDependencies 삭제 (프로덕션 이미지 최적화)
 
# 패키지 설치 경로 디버깅
npm explain react       # react 가 왜 설치됐는지 (어떤 패키지가 요구하는지)

⚙️ .npmrc 로 install 동작 제어

.npmrc 파일은 npm 의 동작 방식을 세밀하게 제어한다.

# .npmrc (영수네 커뮤니티 권장 설정)
 
# 🦁 [시스템 보호] Node.js 버전이 안 맞으면 아예 설치 단계에서 차단해라!
engine-strict=true
 
# [버전 엄격 관리] 설치할 때 package.json에 자동으로 ^ 기호를 붙이지 말고, 정확한 버전만 적어라!
save-exact=true
 
# peerDependencies 충돌이 나면 무시하지 말고 에러를 보여줘라! (기본값)
legacy-peer-deps=false
 
# 🌐 우리 팀 전용 내부 저장소가 있다면 여기서 연결해줍니다.
@youngsoo:registry=https://npm.youngsoo.internal.com/

🔥 save-exact=true 의 영향:

# save-exact=false (기본값)
npm install react
# package.json → "react": "^18.2.0"
 
# save-exact=true
npm install react
# package.json → "react": "18.2.0"

save-exact=true 를 쓰면 package.json 에 정확한 버전이 기록된다. 엄격하게 버전을 관리하는 팀에서 사용한다.

🏁 이번에 배운 내용 총정리

📝 마무리 퀴즈

Q1. npm ci 와 npm install 의 가장 중요한 차이점은?

a) npm ci 는 더 빠른 알고리즘을 사용해 항상 설치 속도가 빠르다
b) npm ci 는 package-lock.json 기준으로 설치하고 lock 파일을 변경하지 않는다
c) npm ci 는 devDependencies 를 자동으로 제외한다
d) npm ci 는 전역 패키지만 설치한다

✅ 정답: b — package-lock.json 기준, lock 변경 안 함

💡 상세 해설:

• 원리 설명: npm ci 의 핵심은 재현 가능성이다. package-lock.json 에 기록된 정확한 버전만 설치하고, lock 파일을 절대 변경하지 않는다. lock 파일이 없으면 에러로 종료한다. CI 환경에서 npm install 을 쓰면 package.json 의 버전 범위 내에서 그 순간 최신 버전이 설치될 수 있어, 어제 통과하던 빌드가 오늘 실패할 수 있다.
• 오답 피드백: a — npm ci 는 node_modules 를 삭제하고 처음부터 설치해 오히려 캐시 없을 때는 느릴 수 있다. c — --omit=dev 옵션을 별도로 써야 한다. d — 전역 설치와 무관하다.
• 📌 핵심 기억법: "CI = 변경 금지. npm ci = lock 파일 변경 금지."

Q2. 팬텀 의존성(Phantom Dependency)이란?

a) package.json 에 선언됐지만 실제로 사용되지 않는 패키지
b) package.json 에 선언하지 않았지만 다른 패키지의 의존성이 호이스팅 되어 import 가 동작하는 패키지
c) node_modules 에 존재하지 않는 패키지
d) 버전이 잘못된 패키지

✅ 정답: b — 직접 설치 안 했지만 호이스팅으로 접근 가능한 패키지

💡 상세 해설:

• 원리 설명: npm 의 플랫 구조 호이스팅으로 인해 A 패키지가 의존하는 B 패키지가 최상위 node_modules 에 올라온다. 내 코드에서 B 를 직접 import 할 수 있지만, A 가 B 를 더 이상 사용하지 않으면 B 가 호이스팅되지 않아 내 코드가 에러난다. 내가 아무것도 바꾸지 않았는데 남의 업데이트로 인해 내 코드가 깨진다.
• 해결: 직접 사용하는 패키지는 package.json 에 명시적으로 선언한다.
• 📌 핵심 기억법: "내 코드에서 쓰는 것은 반드시 내 package.json 에 있어야 한다."

Q3. 🐣 영철이의 테스트 타임 — 긴급 디버깅

영수 PM 이 슬랙을 보냈다. "CI 빌드가 오늘 갑자기 실패했어요. 어제는 됐는데. 코드 변경이 없었다고요?" 영철이가 GitHub Actions 로그를 보니:

Run npm install
...
added 847 packages in 23s

error TS2339: Property 'createServer' does not exist on type ...

그리고 npm list typescript 로 확인해보니 어제는 5.2.0 이었는데 오늘은 5.3.0 으로 설치됐다. 원인과 해결 방법은?

✅ 정답: CI 에서 npm install 을 사용해 lock 파일 없이 매번 최신 버전이 설치됐다. npm ci 로 변경해야 한다.

# 수정 전 (문제 있는 설정)
- name: Install dependencies
  run: npm install
 
# 수정 후 (올바른 설정)
- name: Install dependencies
  run: npm ci

💡 상세 해설:

• 원인: npm install 은 package.json 의 "typescript": "^5.2.0" 범위 내에서 매 실행마다 가능한 최신 버전을 선택한다. 어제 CI 가 돌았을 때는 5.2.0 이 최신이었고, 오늘은 5.3.0 이 나와서 그게 설치됐다. TypeScript 마이너 버전 업데이트에서 타입 체크가 더 엄격해진 것.
• npm ci 를 써야 하는 이유: npm ci 는 package-lock.json 에 기록된 정확히 5.2.0 만 설치한다. lock 파일에 5.2.0 이 기록되어 있는 한, 레지스트리에 5.3.0 이 나와도 무시한다.
• 추가 조치: 개발팀이 TypeScript 5.3.0 으로 업그레이드할 준비가 됐을 때, 로컬에서 npm update typescript 로 lock 파일을 갱신하고 타입 에러를 수정한 다음 커밋한다.
• 📌 핵심 기억법: "CI 에서는 npm ci. 항상. 예외 없이."

🐣 영철이의 퇴근 일기

오늘 드디어 CI 빌드 실패 원인을 잡았다. npm install → npm ci 로 바꿨더니 거짓말처럼 통과됐다. 그렇게 단순한 거였어.

package-lock.json 이 왜 그렇게 길고 복잡한지도 이제 이해한다. 단순히 "버전 기록" 이 아니라 tarball URL 과 SHA-512 해시값까지 적어서 파일 위변조를 막는 거였다. integrity 필드가 공급망 공격의 방어선이라니, 그냥 자동 생성되는 파일인 줄만 알았는데.

💡 오늘의 교훈: "CI 에서는 npm ci. 로컬에서는 npm install. 이 두 줄만 기억하면 '내 로컬에서는 되는데' 지옥에서 탈출할 수 있다."

팬텀 의존성 이야기도 신선했다. 내가 설치 안 한 걸 import 해서 쓸 수 있다는 게... 지금까지 몰랐으면 언젠가 사고가 났을 것 같다. 앞으로는 import 하는 건 무조건 package.json 에 명시하는 습관을 들여야겠다.

오늘은 퇴근하면서 운동 갔다 왔다. 내일은 scripts 랑 라이프사이클 훅 파볼 예정. 생각보다 npm 에 배울 게 이렇게 많다니, 처음엔 그냥 install 치면 되는 줄 알았는데.

🔗 더 알아보기

• npm 공식 문서 — package-lock.json
• npm 공식 문서 — npm ci
• npm 공식 문서 — npm install
• npm 공식 문서 — npmrc