Yarn: install이 integrity checksum mismatch로 실패

안녕하세요, BlueByte입니다. yarn install이 Integrity check failed(최신 Yarn에서는 에러 코드 YN0018)로 멈춰도 여러분 코드에는 문제가 없습니다. Yarn이 가지고 있는 tarball(방금 받았거나 캐시에 있던)의 해시를 yarn.lock에 기록된 checksum과 비교했는데 일치하지 않아, 믿을 수 없는 패키지를 link하기를 거부한 것입니다. 오늘은 이 메시지의 뜻, 지금 어떤 Yarn을 쓰는지 확인하는 법(해결이 다릅니다), checksum이 어긋나는 이유, 원인 확인, 계열별 해결, 그리고 예방까지 하나씩 짚어보겠습니다.

Integrity check failed(그리고 YN0018)이 알려주는 것

Yarn Classic(v1)은 패키지와 계산한 해시를 이름과 함께 보여줍니다:

error Integrity check failed for "left-pad" (computed integrity doesn't match our records, got "sha512-...")

최신 Yarn(Berry, v2+)은 같은 실패에 에러 코드를 붙입니다. Yarn 에러 인덱스는 YN0018을 CACHE_CHECKSUM_MISMATCH라 부르며 "The checksum of a package from the cache doesn't match what the lockfile expects."로 정의합니다. 두 형태 모두 같은 뜻입니다 — Yarn이 가진 바이트로 계산한 해시가 lockfile이 기대하는 해시와 다르다는 것입니다. Yarn은 제 역할을 하는 중입니다: 바이트가 바뀐 패키지를 말없이 설치하지 않습니다.

먼저 지금 어떤 Yarn을 쓰는지 확인하기

해결 명령과 설정 키가 두 계열에서 갈리므로, 무엇이든 건드리기 전에 버전부터 확인합니다:

yarn --version

1.x는 Yarn Classic, 2.x·3.x·4.x는 최신 Yarn(Berry)입니다. 저장소는 package.json의 packageManager나 .yarnrc.yml의 yarnPath로 자체 버전을 고정할 수 있어, PATH의 Yarn이 프로젝트가 실제로 쓰는 Yarn과 늘 같지는 않습니다 — 명령은 프로젝트 디렉터리 안에서 실행하세요.

checksum이 어긋나는 이유

해시가 달라지는 데는 몇 가지 구체적 이유가 있습니다:

• 로컬 캐시가 손상됐습니다 — 다운로드 중단, 설치 중단, 디스크 문제로 잘리거나 변형된 tarball이 남았습니다.
• lockfile이 다른 레지스트리 기준으로 만들어졌습니다 — 사설 미러나 프록시가 tarball을 다시 포장해, 바이트(와 해시)가 lock에 기록된 것과 다릅니다.
• 누군가 디버깅 중 캐시 아카이브를 손으로 고쳤습니다 — Yarn 문서는 이를 YN0018의 가장 흔한 계기로 꼽습니다.
• Yarn 버전이나 해시 알고리즘을 바꿨습니다 — 오래된 lock이 새 resolver가 다르게 계산하는 checksum을 담고 있습니다.
• 드물게 레지스트리가 같은 버전을 다른 바이트로 재배포했습니다 — 있어서는 안 되지만 사설 레지스트리에서 간혹 일어납니다.

이 중 어느 것도 의존성 자체의 버그가 아닙니다. 불일치는 디스크 위의 tarball과 lock의 기록 사이에 있습니다.

메시지 읽기: 캐시 손상인가, 패키지가 바뀐 것인가

불일치가 어디서 나타나는지가 어디를 봐야 할지 알려줍니다. 한 패키지에서, 그것도 내 컴퓨터에서만 난다면 로컬 캐시 손상을 의심하세요. 팀 전체나 CI가 같은 패키지에서 겪는다면 레지스트리나 lockfile을 의심하세요. 실제로 캐시에 무엇이 있는지 봅니다:

yarn cache dir     # Classic: prints the global cache path
ls .yarn/cache     # Berry: per-project cache of .zip archives

동료의 컴퓨터에서 새로 clone해도 불일치가 남는다면, lockfile 자체가 잘못된 checksum을 담고 있어 캐시만 지워서는 안 되고 다시 생성해야 합니다.

최신 Yarn(Berry)에서 고치기

Berry의 가장 깔끔한 해결은 문제 항목을 비우고 다시 받는 것입니다. checksumBehavior 설정이 불일치 시 동작을 정합니다 — throw(기본), reset, update, ignore. 한 번만 비우고 다시 받으려면 reset을 씁니다:

YARN_CHECKSUM_BEHAVIOR=reset yarn install

문서에 따르면 reset은 "the cache entry will be purged and fetched anew"를 뜻합니다. 새 바이트가 정당함을 확인했다면(예: 신뢰하는 미러), 모든 checksum을 다시 받아 재검증하는 쪽을 쓰세요:

yarn install --check-cache

문서는 --check-cache를 "always refetch the packages and ensure that their checksums are consistent"로 설명합니다. 최후의 수단으로 update는 계산된 해시를 yarn.lock에 다시 써넣습니다 — 새 바이트의 출처를 신뢰할 때만 하세요.

Yarn Classic(v1)에서 고치기

Classic에는 checksumBehavior가 없습니다. 캐시를 지우고 재설치합니다. 오래된 node_modules와 그 integrity 마커를 지우고, 캐시를 비운 뒤 새로 설치하세요:

yarn cache clean
rm -rf node_modules
yarn install

lock에 기록된 해시가 틀린 경우(예: 레지스트리를 옮긴 뒤)라면 다시 생성합니다:

yarn install --update-checksums

이는 "update checksums in the yarn.lock lockfile if there's a mismatch between them and their package's checksum"에 해당합니다. 고쳐진 lockfile을 커밋해 모두가 같은 값을 받게 하세요.

실제 사례: CI에서 절반만 받아진 패키지

CI 작업이 yarn install 도중 강제 종료됩니다. 다음 빌드가 이전 실행의 캐시를 복원하고 react-dom@npm:18.3.1에서 YN0018로 실패합니다. 이 패키지 하나에서만, 그것도 CI에서만 — 전형적인 캐시 손상 신호입니다. 그 단계를 YARN_CHECKSUM_BEHAVIOR=reset yarn install로 바꾸자 러너가 잘린 .zip을 비우고 다시 받아, 해시가 맞고 빌드가 통과합니다. lockfile은 하나도 바뀌지 않았습니다 — 기록된 checksum은 내내 옳았고, 캐시의 바이트가 틀렸던 것입니다.

설치가 깨끗한지 확인하고 재발을 막기

CI가 어차피 써야 할 플래그, immutable 설치로 증명합니다:

yarn install --immutable

➤ YN0000: · Done in 3s 421ms

--immutable은 "if the lockfile was to be modified" 중단하므로, checksum이 맞는 깨끗한 설치는 lock 변경 없이 0으로 끝납니다. 재발을 막으려면: yarn.lock을 커밋하고 캐시를 손으로 고치지 마세요. packageManager로 Yarn 버전 하나를 고정해 모두가 같은 방식으로 해시를 계산하게 하세요. CI에서는 --immutable(Berry는 --immutable-cache도)을 써서, 어긋나는 checksum이 조용히 "고쳐지는" 대신 파이프라인에서 크게 실패하게 하세요.

ERESOLVE·registry 404와 어떻게 다른가

checksum 불일치는 바뀐 바이트의 문제입니다. ERESOLVE(npm)나 Yarn의 peer-dependency 에러는 조율할 수 없는 버전의 문제로, 다운로드가 아니라 resolver의 일입니다. 404 Not Found/"couldn't find package"는 그 버전이 레지스트리에 아예 없다는 뜻입니다. 메시지가 아카이브나 integrity가 "doesn't match"라고 하면 이 글의 경우이고, 버전을 resolve하거나 찾을 수 없다고 하면 캐시를 지워도 소용없습니다.