자동 실행 검증 A · Ubuntu 24.04 · npm 10.9.9 · Node 22.23 · 2026-10-25게시 2026-10-25수정 2026-10-29최종 확인 2026-10-25읽기 4분

npm ci 오류 해결: package.json과 package-lock.json 불일치

CI에서 npm ci가 package.json과 package-lock.json이 맞지 않는다며 실패할 때 원인과 해결 방법. npm install과 차이도 정리한다.

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 installnpm ci
lock 파일없으면 만든다. 어긋나면 갱신한다반드시 있어야 한다. 고치지 않는다
기존 node_modules—설치 전에 지운다
개별 패키지 추가가능하다불가능하다. 프로젝트 전체만 설치한다
package.json 변경가능하다고치지 않는다

해결 방법

1. 로컬에서 lock을 갱신한다

package.json이 있는 폴더에서 실행한다.

Terminal window
npm install

package.json의 의존성에 맞게 package-lock.json이 갱신된다.

2. 바뀐 lock을 커밋한다

Terminal window
git add package-lock.json package.json
git 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 문서로 대조했다.

CI 실행 결과 · 수정 전 재현 1건 · 수정 후 11/11 단계 성공
검증 환경 4항목
OSUbuntu 24.04.5
npm10.9.9
Node22.23.3
실행 날짜2026-10-25
실행 기록
[PASS] npm install이 package-lock.json을 만들었다
[PASS] lock에 left-pad가 들어 있다
[PASS] package.json에 is-number를 추가했다
[PASS] lock 해시를 읽었다
수정 전 재현 · 예상된 실패 1건 재현됨수정 전: package.json에만 is-number가 있고 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을 고치지 않았다
수정 후 확인 · 6/6 단계 성공수정 후: npm install로 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을 바꾸지 않았다
이 결과는 글의 명령어를 GitHub Actions의 깨끗한 환경에서 그대로 실행해 자동으로 붙인 것입니다.

주의

  • 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을 커밋한다.

참고 자료