잠금 파일 (Dependency Lockfile)

잠금 파일(Dependency Lockfile)은 프로젝트 의존성의 구체적인 버전과 해결 결과를 기록해 설치 구성을 맞추는 파일입니다. 여기서 잠금은 다른 프로세스의 접근을 막는다는 뜻이 아니라 의존성 선택 결과를 고정한다는 뜻입니다. 재현 가능한 설치를 돕지만 운영체제, 실행 환경, 설치 옵션까지 모두 같게 만드는 파일은 아닙니다.

허용 범위와 실제 선택 결과

프로젝트 설정에 패키지 버전의 허용 범위만 적혀 있으면 설치 시점에 선택되는 세부 버전이 달라질 수 있습니다. 의존성이 다시 요구하는 하위 의존성도 함께 영향을 받습니다. 잠금 파일은 이 선택 결과를 기록해 다른 개발 환경에서도 같은 의존성 구성을 설치할 수 있도록 돕습니다.

npm의 package-lock.json 문서는 설치 과정에서 생성된 정확한 의존성 트리를 기록한다고 설명합니다. package.json이 프로젝트의 의도와 허용 범위를 나타낸다면 package-lock.json은 구체적인 해결 결과를 담습니다. 둘 중 하나가 다른 하나의 모든 역할을 대신하지는 않습니다.

잠금 파일 이름과 형식은 패키지 관리자마다 다릅니다. 파일이 있다는 이유로 다른 관리자를 골라 설치하면 의도한 구성을 따르지 않을 수 있습니다. 프로젝트 안내와 도구 설정을 확인해 어떤 파일을 기준으로 설치하는지 먼저 정합니다.

예를 들어 직접 추가한 패키지 하나의 버전을 유지해도 그 패키지가 참조하는 하위 패키지는 여러 개일 수 있습니다. 직접 의존성 목록만 비교해서는 설치 구성 전체의 차이를 설명하기 어렵습니다. 잠금 파일의 변경 검토에서는 사용자가 추가한 항목과 도구가 함께 갱신한 하위 의존성을 구별해 읽어야 합니다.

설치 명령별 잠금 파일 처리

npm ci 문서에 따르면 이 명령은 기존 잠금 파일을 필요로 하며, package.json과 의존성이 맞지 않으면 잠금 파일을 고치는 대신 오류를 냅니다. 프로젝트 전체를 설치하는 명령이고, 기존 node_modules가 있으면 설치 전에 제거합니다. package.json이나 잠금 파일을 새로 쓰지 않는다는 점도 일반적인 설치 흐름과 구별됩니다.

잠금 파일을 만들 때 의존성 트리에 영향을 주는 옵션을 사용했다면 재현 설치에도 맞는 옵션이 필요할 수 있습니다. 파일만 복사하고 설치 명령의 설정을 빠뜨리면 오류가 나거나 기대한 결과를 얻지 못할 수 있습니다. 자동 빌드 환경과 로컬 환경의 명령을 함께 확인해야 하는 이유입니다.

새 패키지를 추가하거나 버전을 올리는 작업에서는 잠금 파일의 변경이 자연스럽게 발생합니다. 변경 내용을 무조건 되돌리기보다 의도한 패키지와 하위 의존성이 어떻게 달라졌는지 살펴야 합니다. 직접 읽기 어려운 큰 변경이라면 먼저 도구 버전과 파일 형식의 변화가 있었는지 확인합니다.

저장 이력과 실행 환경의 관리

npm의 잠금 파일 문서는 package-lock.json을 소스 저장소에 커밋하도록 설명합니다. 팀원이 같은 변경을 받아 설치할 수 있고, 의존성 변경 이력도 검토할 수 있습니다. 충돌을 해결할 때에는 두 파일의 내용을 임의로 이어 붙이기보다 최종 의존성 의도와 설치 결과가 맞는지 확인합니다.

잠금 파일은 설치할 코드의 모든 안전성을 보증하는 인증서가 아닙니다. 알려진 취약점, 설치 스크립트, 라이선스와 같은 검토는 별도로 필요합니다. 버전을 고정했다는 사실과 해당 버전이 프로젝트 요구에 적합하다는 판단도 구분합니다.

운영체제별 의존성이나 실행 도구 버전 때문에 결과가 달라질 수 있으므로 재현 범위를 정확히 기록합니다. 실패한 설치를 점검할 때 잠금 파일을 삭제하면 기존 문제의 단서를 잃을 수 있습니다. 먼저 오류 메시지와 사용한 관리자·버전·옵션을 확인하고 변경 전 파일을 보존하는 편이 원인 추적에 도움이 됩니다.