30초 요약
npm ci는package.json과package-lock.json이 어긋나면 lock을 고치지 않고 오류로 끝난다.- 로컬에서
npm install로 lock을 갱신하고, 바뀐package-lock.json을 함께 커밋하면 해결된다. npm ci는 설치 전에node_modules를 지우고,package.json과 lock을 고치지 않는다.npm install은 lock을 갱신한다.
증상
로컬에서는 npm install이 잘 되는데 CI에서 npm ci를 돌리면 다음 문장으로 시작하는 오류가 나며 멈춘다.
npm ci can only install packages when your package.json and package-lock.json or npm-shrinkwrap.json are in sync.보통 package.json에 의존성을 추가하거나 버전 범위를 고쳤는데 package-lock.json은 커밋하지 않았을 때 생긴다.
원인
npm ci는 lock 파일대로 설치하는 명령이다. 공식 문서는 package.json과 lock의 의존성이 맞지 않으면 npm ci가 오류로 종료하고, lock을 갱신하지 않는다고 설명한다. npm install은 이런 차이를 만나면 lock을 맞춰 준다. 그래서 같은 저장소에서 로컬 설치는 성공하고 CI만 실패한다.
둘의 차이는 다음과 같다.
npm install | npm ci | |
|---|---|---|
| lock 파일 | 없으면 만든다. 어긋나면 갱신한다 | 반드시 있어야 한다. 고치지 않는다 |
기존 node_modules | — | 설치 전에 지운다 |
| 개별 패키지 추가 | 가능하다 | 불가능하다. 프로젝트 전체만 설치한다 |
package.json 변경 | 가능하다 | 고치지 않는다 |
해결 방법
1. 로컬에서 lock을 갱신한다
package.json이 있는 폴더에서 실행한다.
npm installpackage.json의 의존성에 맞게 package-lock.json이 갱신된다.
2. 바뀐 lock을 커밋한다
git add package-lock.json package.jsongit commit -m "의존성 추가와 lock 갱신"lock만 빼고 커밋하면 CI에서 같은 오류가 되풀이된다.
3. 플래그를 쓴 lock이면 같은 설정을 CI에도 준다
lock을 만들 때 --legacy-peer-deps나 --install-links 같은 플래그를 썼다면 npm ci에도 같은 플래그가 필요하다. 없으면 오류가 날 가능성이 크다. 이런 설정은 .npmrc에 적어 커밋해 둔다.
확인
verify.sh는 임시 폴더에서 left-pad 하나로 lock을 만든 뒤 package.json에만 is-number를 추가해 npm ci를 돌렸다. 이어서 npm install로 lock을 갱신하고 npm ci를 다시 돌렸다. 두 번째 npm ci 전에는 node_modules에 임의 폴더를 끼워 두어 npm ci가 node_modules를 지우는지도 확인했다.
검증 범위: 불일치 오류 재현, npm install로 lock 갱신, npm ci의 node_modules 삭제와 lock 미변경은 실행으로 확인했다. lock이 없을 때의 동작, 개별 패키지 추가 불가, package.json을 고치지 않는 것, 플래그 불일치는 npm ci 문서로, 원인 절 표의 npm install 칸(개별 패키지 추가 가능, package.json 변경)은 npm install 문서로 대조했다.
검증 환경 4항목
| OS | Ubuntu 24.04.5 |
|---|---|
| npm | 10.9.9 |
| Node | 22.23.3 |
| 실행 날짜 | 2026-10-25 |
[PASS] npm install이 package-lock.json을 만들었다 [PASS] lock에 left-pad가 들어 있다 [PASS] package.json에 is-number를 추가했다 [PASS] lock 해시를 읽었다
[XFAIL] npm ci가 package.json과 lock 불일치로 실패 — 예상된 실패 재현됨 (/can only install packages when your package.json and package-lock.json/)
> 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.
[PASS] 실패한 npm ci는 lock을 고치지 않았다[PASS] lock에 is-number가 들어갔다 [PASS] 갱신한 lock 해시를 읽었다 npm warn deprecated left-pad@1.3.0: use String.prototype.padStart() added 2 packages in 157ms [PASS] npm ci 성공 [PASS] npm ci가 기존 node_modules를 지우고 다시 설치했다 (끼워 둔 폴더가 없다) [PASS] npm ci 뒤 is-number가 설치돼 있다 [PASS] npm ci는 lock을 바꾸지 않았다
주의
- lock을
.gitignore에 넣지 않는다.npm ci는 lock이 없으면 설치를 진행하지 않는다. - CI 단계에서
npm install로 바꿔 오류를 피하지 않는다. lock이 어긋난 채로 통과해 버려, 로컬과 CI가 서로 다른 버전을 설치해도 알아채지 못한다. npm ci는 설치 전에node_modules를 지운다. 로컬에서 손으로 넣어 둔 파일이 있으면 사라진다.
자주 묻는 질문
npm ci가 lock 파일을 자동으로 고쳐 주지 않는 이유는 무엇인가?
npm ci는 lock에 적힌 그대로 재현 설치를 하는 명령이라 package.json이나 lock을 고치지 않는다. lock을 고치는 일은 npm install의 몫이다.
CI에서는 항상 npm ci를 써야 하나?
npm ci는 CI·배포처럼 같은 결과를 재현해야 하는 자동화 환경용 명령이다. lock을 갱신하는 단계만 npm install을 쓴다.
npm ci로 패키지 하나만 추가할 수 있나?
없다. 프로젝트 전체만 설치하며 개별 의존성 추가는 지원하지 않는다. 추가는 npm install <패키지>로 하고 바뀐 lock을 커밋한다.