로컬에선 잘 되는데 CI에서 npm ci 가 lock file 불일치로 계속 실패합니다

Question

깃허브 액션에서 npm ci 로 설치하는데 자꾸 이런 에러로 죽습니다. 로컬에서 npm install 하면 아무 문제 없이 되고요.

npm error `npm ci` can only install packages when your package.json and
npm error package-lock.json are in sync. Please update your lock file with
npm error `npm install` before continuing.
npm error Missing: some-lib@2.4.0 from lock file

팀에서 저는 npm, 다른 분은 예전에 yarn을 쓰다가 최근에 pnpm으로 넘어가자는 얘기가 나온 상태라 레포에 package-lock.json 이랑 pnpm-lock.yaml 이 둘 다 있습니다. package.json 은 제가 어제 라이브러리 하나 추가하면서 바꿨고요.

lock 파일을 지우고 다시 만들어야 하나 싶은데, 함부로 지웠다가 팀 전체 빌드가 깨질까 봐 손을 못 대고 있습니다. 어떻게 정리하는 게 맞을까요?

김영삼 · Accepted Answer

원인은 명확합니다. package.json은 어제 라이브러리 추가로 바뀌었는데 package-lock.json이 그 변경을 반영 못 한 채로 커밋된 겁니다. npm ci 는 install과 달리 lock을 절대 수정하지 않고, package.json과 lock이 100% 일치할 때만 설치합니다. 안 맞으면 그냥 죽는 게 정상 동작이에요(재현 가능한 빌드가 목적이라). 로컬 npm install은 lock을 그때그때 갱신해버려서 안 걸렸던 거고, 님 로컬 lock은 최신이지만 그게 커밋이 안 됐거나 CI가 받은 lock이 옛날 것일 겁니다.

당장 고치려면 로컬에서 npm install 한 번 더 돌려서 package-lock.json이 갱신되게 하고, 그 lock 파일을 반드시 같이 커밋해서 push 하세요. package.json 바꾸면 lock도 항상 같이 커밋한다고 생각하시면 됩니다. 그러면 CI npm ci가 통과해요.

더 큰 문제는 lock 파일이 여러 종류 섞여있는 겁니다. package-lock.json(npm)이랑 pnpm-lock.yaml(pnpm)이 같이 있으면 사람마다 다른 툴로 설치해서 서로 다른 버전이 깔리고 이런 사고가 계속 납니다. 팀에서 매니저를 하나로 정하세요. pnpm으로 갈 거면 pnpm-lock.yaml만 남기고 package-lock.json은 지우고, CI도 npm ci 대신 pnpm install --frozen-lockfile 로 바꿔야 합니다. package.json에 packageManager 필드를 박고 corepack을 쓰면 팀원들이 강제로 같은 매니저를 쓰게 돼서 이런 혼선이 사라집니다.

pnpm_arum · Answer

일단 lock 갱신해서 커밋하니 CI는 통과했습니다. 근데 pnpm으로 넘어가는 김에 여쭤보면, package-lock.json 지우고 pnpm install 하면 지금 npm으로 깔려있던 버전들이 그대로 유지되나요? 아니면 버전이 다 달라져서 또 뭔가 깨질 수 있나요?

김영삼 · Answer

버전이 달라질 수 있습니다. pnpm은 package-lock.json을 안 읽어서, 처음 pnpm install 하면 package.json의 버전 범위(^, ~)를 기준으로 새로 해석해 pnpm-lock.yaml을 만듭니다. 그 과정에서 마이너/패치가 최신으로 올라가 기존 npm lock에 박혀있던 정확한 버전과 달라질 수 있어요. 대부분은 괜찮지만 가끔 트랜지티브 의존성이 올라가면서 뭔가 깨지는 게 나옵니다.

그래서 매니저 전환은 별도 브랜치에서 하세요. package-lock.json 지우고 pnpm install 해서 pnpm-lock.yaml 만든 다음, 그 브랜치에서 전체 테스트랑 빌드를 돌려 실제로 앱이 도는지 확인하고 머지하는 겁니다. 그냥 갈아엎지 마시고요. 또 pnpm은 기본이 엄격한 격리 구조라, 그동안 npm의 느슨한 hoisting 덕에 우연히 됐던 'package.json에 선언 안 한 의존성 직접 import' 같은 게 pnpm에선 모듈 못 찾음으로 터질 수 있습니다. 그런 게 나오면 진짜 의존성을 package.json에 제대로 추가하면 돼요. 전환 자체는 그만한 값어치가 있습니다.

pnpm_arum · Answer

별도 브랜치에서 테스트까지 돌려보고 넘어가라는 조언 새겨듣겠습니다. 안 그래도 그냥 지우려던 참이었는데 말리셔서 다행이에요. 감사합니다 🙏

댓글 4