yarn install error - integrity check failed 해결하기

에러 로그의 내용은 다음과 같습니다.

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

이 에러는 Yarn 패키지 매니저에서 패키지의 무결성을 확인하는 과정에서 문제가 발생한 것입니다. 패키지의 무결성은 해당 패키지의 내용이 변경되지 않았음을 보장하는데 사용되는 체크섬에 관련된 오류입니다.

잠깐! 여기서 체크섬(Checksum)이란?

체크섬은 데이터의 무결성을 확인하기 위한 일련의 문자열입니다.
Yarn에서의 체크섬은 패키지의 무결성을 보장하기 위해 사용됩니다.
이를 통해 다운로드한 데이터가 손상되지 않았는지 확인합니다. 만약 데이터에 변경이 있다면, 체크섬이 일치하지 않을 것이며 패키지 매니저는 경고를 발생시키거나 다운로드를 실패시킵니다.

Yarn은 패키지를 설치할 때 yarn.lock 파일에 패키지의 체크섬을 저장합니다. 이렇게 하면 같은 의존성을 가진 프로젝트가 항상 같은 버전의 패키지를 사용하고, 해당 패키지의 내용이 변경되지 않았는지를 보장할 수 있습니다.

체크섬은 주로 해시 함수 (예: SHA-256)를 사용하여 생성됩니다. 패키지 매니저는 이러한 알고리즘을 통해 패키지의 내용으로부터 고유한 체크섬을 생성하고 저장합니다. 다운로드된 패키지의 내용이나 버전이 변경되면, 체크섬도 변경되므로 이를 통해 무결성을 확인할 수 있습니다.

---

체크섬은 yarn.lock에 저장되어 있습니다.

저의 경우 예상되는 원인은 패키지 내용이 변경되어서 라고 생각합니다.
패키지의 내용이 다운로드된 이후에 변경되었을 경우 발생할 수 있습니다. 이는 패키지의 무결성이 깨졌다는 것을 의미합니다.

제가 시도한 방법은 다음과 같습니다.

1. 먼저 캐시를 삭제합니다.
2. yarn cache clean
3. 체크섬을 강제로 업데이트합니다.—update-checksums옵션을 사용하면 Yarn에게 체크섬을 강제로 업데이트하도록 명령합니다. 이를 통해 yarn.lock파일과 패키지 내용이 정확히 일치하도록 합니다.
4. yarn --update-checksums

보통 Yarn은 패키지를 설치하면서 해당 피키지의 체크섬을 자동으로 생성하고 yarn.lock에 저장합니다. 이를 통해서 패키지의 버전 및 내용이 변경되지 않았는지를 추적할 수 있습니다. 하지만 때때로 수동으로 패키지를 수정하거나 업데이트할 때, 체크섬이 올바르게 업데이트되지 않을 수 있습니다.

어쩌다 이렇게 된 저의 상황은 사내 Nexus Repository 사용 중 외부 저장소에서 모든 버전을 받아올 수 있게 허용한 상태에서 패키지 버전을 고정하지 않고 다운로드한 것이 원인이었습니다. 캐럿으로 버전을 명시하고 있던 패키지들은 가장 latest minor 혹은 latest patch 버전들을 다운로드하였습니다.

저희의 빌드 환경은 Node 16.21.1 버전까지만 지원하는 상황이었음에도 불구하고 다운로드 받은 패키지들은 Node 20.x.x 버전에서 지원하는 패키지들 투성이었습니다.

다행히 checksum 업데이트를 통해 이 문제를 해결할 수 있었습니다.

끗!