package.json은 "이 범위 안의 버전이면 된다"는 조건을 적는 파일이고, package-lock.json은 그 조건으로 실제 설치된 버전과 integrity 해시를 기록하는 파일입니다. npm install은 두 파일이 어긋나면 lock 파일을 고쳐 쓰고, npm ci는 고치지 않고 오류로 멈춥니다. 그래서 개발할 때는 npm install을, 빌드와 배포에서는 npm ci를 씁니다.
준비물
| 항목 | 내용 |
|---|---|
| Node.js | v24.15.0 |
| npm | 11.12.1 |
| 실습 패키지 | ms 2.1.1과 2.1.3 (의존성이 없는 작은 패키지) |
| 실습 위치 | 빈 폴더 하나 (실제 프로젝트와 분리) |
| 셸 | bash (Windows에서는 Git Bash) |
ms를 고른 이유는 2.1.1 뒤에 2.1.2와 2.1.3이 나와 있어서, 범위와 고정 버전의 차이가 바로 드러나기 때문입니다.
1. 프로젝트 만들고 패키지 설치하기
빈 폴더에서 package.json을 만듭니다.
npm init -y
Wrote to .../npm-lock-lab/package.json:
{
"name": "npm-lock-lab",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC",
"type": "commonjs"
}
최신 버전이 아닌 2.1.1을 지정해 설치합니다.
npm install ms@2.1.1
added 1 package, and audited 2 packages in 769ms
found 0 vulnerabilities
2. package.json에 적히는 버전 범위
설치 뒤의 package.json을 봅니다.
cat package.json
{
"name": "npm-lock-lab",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC",
"type": "commonjs",
"dependencies": {
"ms": "^2.1.1"
}
}
명령에는 2.1.1이라고 썼는데 파일에는 ^2.1.1이 들어갔습니다. 앞의 ^(caret)은 "2.1.1 이상, 3.0.0 미만"이라는 범위 표시입니다. 이 범위에 들어가는 버전이 레지스트리에 몇 개 있는지 확인합니다.
npm view ms versions
'2.0.0',
'2.1.0',
'2.1.1',
'2.1.2',
'2.1.3',
출력은 2.x 정식 버전만 남기고 줄였습니다. ^2.1.1을 만족하는 버전은 2.1.1, 2.1.2, 2.1.3 세 개입니다. package.json만으로는 셋 중 무엇이 설치될지 정해지지 않습니다.
3. package-lock.json에 적히는 설치 버전과 해시
같은 설치로 만들어진 package-lock.json을 봅니다.
cat package-lock.json
{
"name": "npm-lock-lab",
"version": "1.0.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "npm-lock-lab",
"version": "1.0.0",
"license": "ISC",
"dependencies": {
"ms": "^2.1.1"
}
},
"node_modules/ms": {
"version": "2.1.1",
"resolved": "https://registry.npmjs.org/ms/-/ms-2.1.1.tgz",
"integrity": "sha512-tgp+dl5cGk28utYktBsrFqA7HKgrhgPsg6Z/EfhWI4gl1Hwq8B/GmY/0oXZ6nF8hDVesS/FpnYaD/kOWhYQvyg==",
"license": "MIT"
}
}
}
node_modules/ms 항목에서 읽을 값은 세 가지입니다.
- version: 범위가 아니라
2.1.1한 버전만 적힙니다. - resolved: 패키지 파일(tarball)을 받은 주소입니다.
- integrity: 그 파일의 SHA-512 해시입니다. 설치할 때 받은 파일의 해시가 이 값과 다르면 npm은 설치를 중단합니다.
lock 파일의 해시가 레지스트리에 등록된 값과 같은지 확인합니다.
npm view ms@2.1.1 dist.integrity
sha512-tgp+dl5cGk28utYktBsrFqA7HKgrhgPsg6Z/EfhWI4gl1Hwq8B/GmY/0oXZ6nF8hDVesS/FpnYaD/kOWhYQvyg==
두 값이 같습니다. lock 파일을 저장소에 올려 두면, 다른 PC에서도 같은 버전의 같은 파일이 설치됩니다.
4. lock 파일이 있을 때의 npm install: 고정 버전 설치
node_modules를 지우고 다시 설치합니다. 범위 안에 더 높은 2.1.3이 있지만 lock 파일은 2.1.1을 가리키고 있습니다.
rm -rf node_modules
npm install
npm ls ms
added 1 package, and audited 2 packages in 727ms
found 0 vulnerabilities
npm-lock-lab@1.0.0 .../npm-lock-lab
`-- ms@2.1.1
2.1.1이 설치됐습니다. lock 파일이 package.json의 범위를 만족하는 동안에는 npm install도 lock 파일의 버전을 그대로 씁니다.
5. lock 파일이 없을 때 달라지는 버전
이번에는 lock 파일까지 지웁니다. 뒤에서 다시 쓰려고 복사본을 남겨 둡니다.
cp package-lock.json lock-backup.json
rm -rf node_modules package-lock.json
npm install
npm ls ms
added 1 package, and audited 2 packages in 692ms
found 0 vulnerabilities
npm-lock-lab@1.0.0 .../npm-lock-lab
`-- ms@2.1.3
package.json은 한 글자도 바뀌지 않았는데 2.1.3이 설치됐습니다. lock 파일이 없으면 npm은 범위 안에서 가장 높은 버전을 고릅니다. lock 파일을 저장소에 올리지 않은 프로젝트는 설치한 날짜에 따라 다른 코드를 받게 됩니다.
6. npm install과 npm ci 비교
복사해 둔 lock 파일을 되돌려 놓습니다. 지금 node_modules에는 2.1.3이, lock 파일에는 2.1.1이 들어 있습니다. 이 상태에서 npm ci를 실행합니다.
cp lock-backup.json package-lock.json
npm ci
npm ls ms
added 1 package, and audited 2 packages in 681ms
found 0 vulnerabilities
npm-lock-lab@1.0.0 .../npm-lock-lab
`-- ms@2.1.1
npm ci는 기존 node_modules를 지우고 lock 파일에 적힌 버전으로 처음부터 다시 설치합니다. 그래서 이미 설치가 끝난 폴더에서 다시 실행해도 매번 설치 과정을 거칩니다. 다음은 4번까지 진행한 상태(2.1.1 설치 완료)에서 두 명령을 한 번씩 더 실행한 출력입니다.
npm install
up to date, audited 2 packages in 932ms
found 0 vulnerabilities
npm ci
added 1 package, and audited 2 packages in 813ms
found 0 vulnerabilities
npm install은 바꿀 것이 없어 up to date로 끝났고, npm ci는 added 1 package로 다시 설치했습니다.
lock 파일이 없는 폴더에서는 npm ci가 실행되지 않습니다. 5번에서 lock 파일을 지운 직후에 실행한 결과입니다.
npm ci
echo $?
npm error code EUSAGE
npm error
npm error The `npm ci` command can only install with an existing package-lock.json or
npm error npm-shrinkwrap.json with lockfileVersion >= 1. Run an install with npm@5 or
npm error later to generate a package-lock.json file, then try again.
1
오류 메시지 뒤에 이어지는 사용법 안내와 로그 파일 경로는 뺐습니다. 종료 코드는 1입니다.
7. 두 파일이 어긋날 때 멈추는 npm ci
package.json의 범위만 ^2.1.3으로 바꿉니다. lock 파일에 적힌 2.1.1은 이제 범위 밖입니다.
npm pkg set dependencies.ms=^2.1.3
npm ci
echo $?
npm error code EUSAGE
npm error
npm error `npm ci` can only install packages when your package.json and package-lock.json or npm-shrinkwrap.json are in sync. Please update your lock file with `npm install` before continuing.
npm error
npm error Invalid: lock file's ms@2.1.1 does not satisfy ms@2.1.3
1
여기서도 사용법 안내와 로그 파일 경로는 뺐습니다. Invalid: 줄이 어떤 패키지가 어긋났는지 알려 줍니다. 같은 상태에서 npm install을 실행하면 결과가 다릅니다.
npm install
npm ls ms
changed 1 package, and audited 2 packages in 710ms
found 0 vulnerabilities
npm-lock-lab@1.0.0 .../npm-lock-lab
`-- ms@2.1.3
npm install은 멈추지 않고 lock 파일을 새 범위에 맞게 바꿔 놓았습니다. lock 파일에서 버전과 해시가 함께 바뀐 것을 확인합니다.
grep -n '"version"\|"integrity"' package-lock.json
3: "version": "1.0.0",
9: "version": "1.0.0",
16: "version": "2.1.3",
18: "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
두 파일이 다시 맞았으므로 npm ci도 통과합니다.
npm ci
added 1 package, and audited 2 packages in 697ms
found 0 vulnerabilities
8. integrity 불일치와 설치 중단
3번에서 본 integrity 값이 실제로 검사되는지 확인합니다. 프로젝트를 다른 폴더에 복사하고, lock 파일의 해시 앞 네 글자만 AAAA로 바꿉니다. --cache로 빈 cache 폴더를 지정해 파일을 레지스트리에서 새로 받게 합니다.
mkdir _tamper
cp package.json package-lock.json _tamper/
cd _tamper
sed -i 's#sha512-6Flz#sha512-AAAA#' package-lock.json
npm ci --cache ./fresh-cache
echo $?
npm error code EINTEGRITY
npm error sha512-AAAAubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA== integrity checksum failed when using sha512: wanted sha512-AAAAubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA== but got sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==. (2967 bytes)
1
앞쪽의 재시도 경고(npm warn)와 로그 파일 경로는 뺐습니다. wanted는 lock 파일에 적힌 값이고 got은 받은 파일에서 계산한 값입니다. 둘이 다르면 EINTEGRITY 오류가 나고 종료 코드는 1입니다. 레지스트리의 파일이 바뀌었거나 lock 파일이 잘못 고쳐졌을 때 이 오류를 보게 됩니다.
9. 비교 정리
두 파일의 차이입니다.
| 구분 | package.json | package-lock.json |
|---|---|---|
| 적히는 값 | 버전 범위 (^2.1.1) |
설치된 버전 하나 (2.1.1) |
| 추가 정보 | 스크립트, 이름, 라이선스 | resolved 주소, integrity 해시 |
| 고치는 주체 | 사람 또는 npm install <패키지> |
npm(자동) |
| 저장소 커밋 | 올림 | 올림 |
두 명령의 차이입니다. 모두 위 실험에서 확인한 동작입니다.
| 상황 | npm install | npm ci |
|---|---|---|
| lock 파일이 없을 때 | 범위 안 최고 버전 설치, lock 파일 생성 | EUSAGE 오류, 종료 코드 1 |
| 두 파일이 맞을 때 | lock 파일 버전 설치 | lock 파일 버전 설치 |
| 두 파일이 어긋날 때 | lock 파일을 고쳐 쓰고 설치 | EUSAGE 오류, 종료 코드 1 |
| 이미 설치된 폴더에서 | up to date |
node_modules를 지우고 다시 설치 |
| 쓰는 곳 | 패키지를 추가하거나 올릴 때 | CI 빌드, 배포 이미지 빌드 |
CI에서 npm ci를 쓰면 누군가 package.json만 고치고 lock 파일을 빠뜨린 커밋이 빌드 단계에서 걸립니다. lock 파일이 바뀐 커밋은 어떤 패키지의 버전과 해시가 바뀌었는지 리뷰에서 확인합니다. 설치 스크립트를 막는 방법은 npm 설치 때 실행되는 스크립트를 막고 락파일 바뀐 곳 찾기에 있습니다. 설치된 버전의 취약점은 Node.js 시작하기: 프로젝트 만들기와 npm audit 점검에서 확인합니다.
자주 묻는 질문
package-lock.json을 .gitignore에 넣어도 됩니까?
넣지 않습니다. lock 파일이 저장소에 없으면 5번 실험처럼 설치한 날짜에 따라 다른 버전이 들어옵니다.
npm ci가 EUSAGE로 실패하면 무엇을 해야 합니까?
개발 PC에서 npm install을 실행해 lock 파일을 맞춘 뒤, package.json과 package-lock.json을 같은 커밋에 올립니다.
package.json에 ^ 없이 2.1.1로 적으면 lock 파일이 없어도 됩니까?
직접 의존성 버전만 고정될 뿐이고, 그 패키지가 다시 불러오는 하위 패키지의 버전과 integrity 해시는 lock 파일에만 기록됩니다.
이 글의 다음 단계
- Node.js 시작하기: 프로젝트 만들기와 npm audit 점검Node.js 버전을 확인하고 npm 프로젝트를 만든 뒤, 취약한 lodash 4.17.15를 설치해 npm audit가 무엇을 보고하는지 확인합니다. npm audit fix로 고친 뒤 다시 점검하는 순서까지 실제 출력으로 정리합니다.
- npm 설치 때 실행되는 스크립트를 막고 락파일 바뀐 곳 찾기내 로컬 npm 레지스트리 Verdaccio에 무해한 패키지 둘을 올려 postinstall이 설치 때 실행되는 것을 재현하고, ignore-scripts와 npm rebuild로 막습니다. 이어서 package-lock.json에서 resolved와 integrity가 바뀐 줄, 예상 밖 레지스트리, 새로 생긴 설치 스크립트를 찾는 보고서를 만들고 npm audit signatures와 최소 버전 나이 정책도 시험합니다.
이 내용을 팀 교육으로 진행하고 싶으신가요?
인원, 수준, 일정에 맞춰 실습 환경까지 준비해 진행합니다. 대상과 기간을 알려 주시면 구성을 제안해 드립니다.
교육 문의하기메일로 보내실 수도 있습니다: fankh111@gmail.com