package-lock.json을 함부로 삭제하면 안 되는 이유

프로젝트 루트에 package-lock.json이 있으면 왜 이게 있는지 잘 모르고 그냥 gitignore에 넣거나 지워버리는 경우가 있다. 의존성 충돌이 생겼을 때도 일단 지우고 npm install을 다시 해보는 방법이 자주 권장된다. 지우면 안 되는 이유를 정확히 이해하면 더 나은 방법을 쓸 수 있다.

lockfile이 하는 일

package.json에는 보통 "react": "^18.0.0" 처럼 범위로 버전이 적혀 있다. ^는 마이너 버전까지 허용하는 의미라서 18.3.1이 설치될 수도 있고 18.2.0이 설치될 수도 있다. 언제 설치하느냐에 따라 달라진다.

package-lock.json은 실제로 설치된 버전과 의존성 트리를 정확히 기록한다. 이 파일이 있으면 다음번에 npm install을 실행해도 동일한 버전이 설치된다.

# lockfile을 사용해서 정확히 동일한 버전을 설치 (CI에서 권장)
npm ci

# lockfile을 무시하고 새로 계산해서 설치
npm install

npm ci는 package-lock.json과 node_modules가 일치하지 않으면 에러를 낸다. CI 파이프라인에서 npm install 대신 npm ci를 쓰는 이유가 이것이다.

지웠을 때 실제로 생길 수 있는 문제

팀원 A가 개발할 때 설치된 어떤 패키지가 4.2.1이었다고 하자. lockfile을 지우고 팀원 B가 npm install을 하면 그 사이 패키지 새 버전 4.3.0이 나왔을 경우 B에게는 4.3.0이 설치된다. 마이너 업데이트는 대부분 괜찮지만 가끔 breaking change가 들어오거나 버그가 포함된다. 로컬에서는 B만 이상한 동작을 겪고 A는 재현이 안 된다.

CI 서버에서는 더 심각하다. 새로 npm install을 실행하는 CI는 항상 최신 버전을 가져오기 때문에 배포할 때마다 다른 버전이 들어갈 수 있다.

충돌 해결이 목적이라면 다른 방법을 써라

lockfile을 지우고 싶은 상황은 주로 peer dependency 충돌이나 npm install 자체가 에러를 낼 때다. 이때는 지우는 대신 아래 방법을 먼저 시도한다.

# node_modules만 지우고 lockfile은 남긴 채 재설치
rm -rf node_modules
npm install

# 특정 패키지만 최신으로 올리기
npm update some-package

# peer dependency 경고를 일단 무시하고 설치 (호환성 확인 후)
npm install --legacy-peer-deps

lockfile 자체에 문제가 있어서 어쩔 수 없이 새로 만들어야 한다면, 지운 직후 바로 npm install을 실행하고 새로 생긴 package-lock.json을 커밋해야 한다. 그냥 gitignore에 추가하는 건 문제를 미루는 것이다.