# package.json과 package-lock.json 차이: npm ci로 확인하기

> package.json에는 허용하는 버전 범위가, package-lock.json에는 실제로 설치된 버전과 integrity 해시가 적힙니다. 같은 프로젝트에서 npm install과 npm ci를 번갈아 실행해 두 파일의 역할과 두 명령의 차이를 실제 출력으로 확인합니다.

- 주소: https://copyandrun.com/blog/npm-package-json-lockfile-basics/
- 분야: DevSecOps
- 발행일: 2026-11-16
- 태그: npm, package.json, package-lock.json, npm ci, Node.js

`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`을 만듭니다.

```bash
npm init -y
```

```text
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을 지정해 설치합니다.

```bash
npm install ms@2.1.1
```

```text
added 1 package, and audited 2 packages in 769ms

found 0 vulnerabilities
```

## 2. package.json에 적히는 버전 범위

설치 뒤의 `package.json`을 봅니다.

```bash
cat package.json
```

```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 미만"이라는 범위 표시입니다. 이 범위에 들어가는 버전이 레지스트리에 몇 개 있는지 확인합니다.

```bash
npm view ms versions
```

```text
  '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`을 봅니다.

```bash
cat package-lock.json
```

```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 파일의 해시가 레지스트리에 등록된 값과 같은지 확인합니다.

```bash
npm view ms@2.1.1 dist.integrity
```

```text
sha512-tgp+dl5cGk28utYktBsrFqA7HKgrhgPsg6Z/EfhWI4gl1Hwq8B/GmY/0oXZ6nF8hDVesS/FpnYaD/kOWhYQvyg==
```

두 값이 같습니다. lock 파일을 저장소에 올려 두면, 다른 PC에서도 같은 버전의 같은 파일이 설치됩니다.

## 4. lock 파일이 있을 때의 npm install: 고정 버전 설치

`node_modules`를 지우고 다시 설치합니다. 범위 안에 더 높은 2.1.3이 있지만 lock 파일은 2.1.1을 가리키고 있습니다.

```bash
rm -rf node_modules
npm install
npm ls ms
```

```text
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 파일까지 지웁니다. 뒤에서 다시 쓰려고 복사본을 남겨 둡니다.

```bash
cp package-lock.json lock-backup.json
rm -rf node_modules package-lock.json
npm install
npm ls ms
```

```text
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`를 실행합니다.

```bash
cp lock-backup.json package-lock.json
npm ci
npm ls ms
```

```text
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 설치 완료)에서 두 명령을 한 번씩 더 실행한 출력입니다.

```bash
npm install
```

```text
up to date, audited 2 packages in 932ms

found 0 vulnerabilities
```

```bash
npm ci
```

```text
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 파일을 지운 직후에 실행한 결과입니다.

```bash
npm ci
echo $?
```

```text
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은 이제 범위 밖입니다.

```bash
npm pkg set dependencies.ms=^2.1.3
npm ci
echo $?
```

```text
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`을 실행하면 결과가 다릅니다.

```bash
npm install
npm ls ms
```

```text
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 파일에서 버전과 해시가 함께 바뀐 것을 확인합니다.

```bash
grep -n '"version"\|"integrity"' package-lock.json
```

```text
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`도 통과합니다.

```bash
npm ci
```

```text
added 1 package, and audited 2 packages in 697ms

found 0 vulnerabilities
```

## 8. integrity 불일치와 설치 중단

3번에서 본 `integrity` 값이 실제로 검사되는지 확인합니다. 프로젝트를 다른 폴더에 복사하고, lock 파일의 해시 앞 네 글자만 `AAAA`로 바꿉니다. `--cache`로 빈 cache 폴더를 지정해 파일을 레지스트리에서 새로 받게 합니다.

```bash
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 $?
```

```text
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 설치 때 실행되는 스크립트를 막고 락파일 바뀐 곳 찾기](/blog/npm-supply-chain-install-script-defense/)에 있습니다. 설치된 버전의 취약점은 [Node.js 시작하기: 프로젝트 만들기와 npm audit 점검](/blog/nodejs-npm-project-audit-first-steps/)에서 확인합니다.

## 자주 묻는 질문

**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 파일에만 기록됩니다.
