명령어를 실행했는데 yarn install, 방금 업데이트한 의존성이 여전히 이전 빌드로 연결됩니다. 혹은 로컬에서는 잘 설치되는데 lockfile을 살짝 바꿨다고 CI가 갑자기 실패하기도 하죠.
이런 상황에서 보통 사람들은 Yarn 캐시 삭제하기 를 검색한 뒤 가장 먼저 나오는 명령어를 복사해서 붙여넣습니다.
어떨 때는 해결되지만, 어떤 때는 아무것도 해결되지 않습니다. 이유는 간단합니다. Yarn의 캐시 동작 방식은 사용 중인 Yarn 버전에 따라 크게 달라지며, 그 차이는 바로 Yarn Classic v1 및 Yarn Berry v2+ 올바른 명령어와 문제 해결 전략을 모두 바꿔야 할 만큼 큽니다.
대부분의 가이드는 yarn cache clean에서 끝납니다. 하지만 그건 시작일 뿐입니다. 중요한 것은 캐시 범위, 프로젝트가 로컬 캐시를 쓰는지 공유 캐시를 쓰는지, 그리고 진짜 문제가 정말 캐시인지입니다. CI와 Docker에서는 잘못된 캐싱 전략이 오래된 패키지 아카이브보다 더 큰 문제를 일으키곤 합니다.
목차
- 빌드가 실패했는데 Yarn 캐시가 원인일 수 있습니다
- Yarn 캐시를 비워야 하는 시점과 이유
- Yarn Classic v1에서 캐시 비우기
- Yarn Berry v2+의 현대적인 캐시 관리
- CI/CD 및 Docker를 위한 Yarn 캐시 베스트 프랙티스
- 자주 발생하는 Yarn 캐시 오류 해결하기
- Yarn 캐시 삭제 관련 자주 묻는 질문
빌드가 실패했는데 Yarn 캐시가 원인일 수 있습니다
익숙한 패턴이 있습니다. 패키지 버전을 올리고, 최신 변경 사항을 pull한 뒤, 다시 install을 실행합니다. 명령은 완료되지만, 앱은 여전히 이전 의존성이 남아 있는 것처럼 동작합니다. 그러다 누군가 캐시를 지우라고 하면, 이게 진짜 해결책인지 아니면 그냥 미신인지 궁금해지기 시작하죠.
진짜 해결책일 수도 있고, 그냥 주의를 딴 데로 돌리는 일일 수도 있습니다.
캐시 문제는 보통 몇 가지 예측 가능한 방식으로 나타납니다. 로컬 패키지가 갱신되지 않거나, CI가 예상치 못한 걸 가져오거나, lockfile상 모든 것이 일치해야 하는데도 새 브랜치가 main 브랜치와 다르게 동작하죠. 이미 파이프라인 전반의 불안정성을 쫓고 있다면, 캐시 디버깅과 함께 더 체계적인 빌드 리뷰를 병행하는 것이 좋습니다. 이 가이드에서 다루는 Capacitor CI/CD 파이프라인의 빌드 실패 해결 방법.
실무 원칙: Yarn clear cache를 정기적인 유지보수 의식이 아니라 진단 도구로 취급하세요.
까다로운 점은 Yarn이 시간이 지나면서 캐시 모델을 바꿨다는 것입니다. 오래된 프로젝트에서는 캐시가 전역으로 공유됩니다. 최신 프로젝트에서는 명령 플래그에 따라 캐시 정리가 프로젝트 로컬에만, 전역에만, 또는 둘 다 적용될 수 있습니다. 그래서 팀원이 “그냥 Yarn 캐시 지워”라고 하면, 첫 질문은 이것이어야 합니다. 어떤 Yarn을 쓰시나요?
그래서 캐시 문제를 제대로 해결하려면 상황 파악부터 시작해야 합니다. 로컬 머신인지 CI 러너인지, Yarn v1인지 Berry인지, 공유 캐시인지 프로젝트 캐시인지. 이걸 알면 명령어가 막연한 시도가 아니라 정확해집니다.
Yarn 캐시를 비워야 하는 시점과 이유
Yarn 캐시를 지우는 건 특정 실패 상황을 염두에 둘 때 의미가 있습니다. 오래된 패키지 아티팩트를 제거하거나, 다운로드가 깨진 상태에서 복구하거나, Yarn이 처음부터 다시 빌드하도록 저장된 패키지를 의도적으로 지울 때 가장 유용합니다.
캐시 문제임을 알 수 있는 증상들
캐시를 지울 만한 대표적인 경우:
- 의존성 업데이트가 안 될 때: 버전을 바꾸거나 로컬 패키지를 다시 빌드했는데도 설치할 때 계속 이전 아티팩트를 가져오는 경우입니다.
- 상태에 의존하는 듯한 설치 실패가 발생할 때: 한 머신에서는 되는데 다른 머신에서는 안 되고, 같은 명령어를 다시 실행해도 계속 같은 문제가 재현되는 경우입니다.
- 로컬 디스크 공간을 확보해야 할 때: 이는 수명이 짧은 CI 환경보다 개발자 머신에서 더 중요하게 작용합니다.
다른 상황들은 단순히 캐시 문제처럼 보일 뿐일 수 있습니다. lockfile이 예상치 못하게 변경되었거나, 워크스페이스 설정이 일관되지 않거나, Docker 빌드가 잘못된 레이어를 무효화하는 경우라면 캐시 삭제로 근본 원인을 해결할 수 없습니다. 앱 빌드를 담당하는 팀은 네이티브 툴링, JavaScript 의존성, 플러그인 업데이트를 동시에 관리하며 이런 문제에 자주 직면합니다. 이런 맥락에서, Capacitor 프로젝트의 의존성 관리 이 실용적인 개요를 곁에 두는 것이 좋습니다.
패키지 트러블슈팅이 아니라 전반적인 머신 정리가 목적이라면 시스템 레벨 가이드도 도움이 됩니다. Mac 개발자 중 Mac 앱 캐시 정리 를 원하는 이들은 패키지 매니저가 저장 공간의 일부일 뿐이라는 걸 자주 알게 됩니다.
Yarn clear cache를 사용하면 안 되는 경우
모든 설치 문제에 대해 Yarn clear cache를 첫 번째 해결책으로 사용하지 마세요.
패키지 상태가 오래되었거나 손상되었다는 증거가 있을 때 사용하세요. 다음과 같은 상황이라면 건너뛰는 것이 좋습니다:
| 상황 | 더 나은 우선 조치 |
|---|---|
| Lockfile drift 현상 | 변경 사항을 검토하고 yarn.lock 일관되게 재설치하세요 |
| Workspace resolution 문제 | Workspace 설정 및 설치 동작 확인 |
| Docker 빌드 속도 저하 | Layer 순서 및 캐시 유지 여부 검토 |
| CI 환경 불일치 | 실제로 복구되는 디렉토리 확인 |
환경 문제로 설치가 잘못되는 경우라면, 캐시를 삭제해도 다음번 잘못된 설치가 더 느려질 뿐입니다.
이 차이를 아는 것이 시간을 아끼는 길입니다. 캐시를 만능 리셋 버튼처럼 다루다 보면 디버깅에 많은 시간을 허비하게 됩니다.
Yarn Classic v1에서 캐시 비우기
Yarn Classic은 많은 개발자가 여전히 모든 Yarn 버전이 작동할 것이라고 예상하는 방식으로 동작합니다. 이는 글로벌 캐시를 사용자 디렉토리에 사용하며, yarn cache clean 해당 공유 캐시를 삭제합니다. Yarn Classic의 공식 문서에서도 이를 설명하고 있으며, 다음 yarn 또는 yarn install 실행 시 캐시가 다시 채워진다고 명시합니다. 사용자 디렉토리 모델은 Yarn Classic 캐시 CLI 문서에 설명되어 있습니다..
명령어가 실제로 삭제하는 것
Yarn v1의 기본 정리 명령어는 다음과 같이 간단합니다:
yarn cache clean
이 명령어는 현재 프로젝트뿐만 아니라 공유 캐시 전체를 삭제합니다. 동일한 머신에서 여러 저장소를 작업한다면 이 점이 중요합니다. 이후 어떤 저장소에서 설치를 진행하든 패키지를 다시 가져와야 할 수도 있습니다.
이러한 공유 캐시 설계는 Yarn v1이 프로젝트 간에 혼란스러운 동작을 일으키는 이유 중 하나입니다. 글로벌 캐시에 남은 오래된 아티팩트가 다른 저장소에 영향을 줄 정도로 오래 남아 있을 수 있으며, 특히 로컬 패키지 개발 시 더욱 그렇습니다.
Yarn Classic의 일반적인 작업 순서는 다음과 같습니다:
- 먼저 clean 명령어를 실행하세요:
yarn cache clean - 필요한 경우 로컬 설치 아티팩트를 제거합니다:
node_modules상태가 여전히 일관되지 않다면 다음 단계로 고려됩니다. - 처음부터 다시 설치합니다: 실행
yarn install다시 실행하여 의존성 그래프가 예상대로 해결되는지 확인합니다.
캐시 위치 확인 방법
캐시 디렉토리를 직접 확인하거나 삭제하려면 Yarn Classic에서 다음 경로를 제공합니다:
yarn cache dir
CLI 명령어로 문제가 해결되지 않거나, 공유 또는 컨테이너 환경에서 캐시 디렉토리의 소유자 계정을 확인해야 할 때 유용합니다.
이전 툴체인을 사용 중이며 로컬 설정을 예측 가능하게 유지하려는 분들을 위해, 다음 가이드를 준비했습니다: Capacitor CLI 단계별 설치 방법 의존성을 깔끔하게 초기화할 때 함께 사용하면 좋습니다.
무작정 정리 명령어를 다시 실행하는 것보다 캐시를 직접 확인하는 것이 훨씬 유용할 때가 많습니다.
v1 프로젝트의 개념은 간단합니다. 하나의 공유 캐시, 하나의 광범위한 정리 명령어, 그리고 다음 install 시 삭제된 항목이 다시 채워지는 방식입니다.
Yarn Berry v2+의 현대적인 캐시 관리 방식
Yarn Berry는 패러다임을 바꿨습니다. Yarn v1에 익숙하다면, 캐시 정리가 더 이상 단순히 "글로벌 스토어를 싹 비우고 다시 시도하는 것"이 아니라는 점이 가장 큰 차이점입니다. Berry는 훨씬 정밀한 제어를 지원하며, 이는 타겟을 정확히 알 때 매우 유용합니다.
Berry는 캐시 모델을 변경했습니다
최신 Yarn에서 캐시 동작은 프로젝트와 훨씬 더 밀접하게 연결되어 있습니다. 이는 프로젝트 레벨의 제어, Plug’n’Play, 그리고 의존성을 머신 전체의 단일 캐시 모델이 아닌 레포지토리와 함께 관리하는 Berry의 광범위한 접근 방식에 부합합니다.
이 때문에 과거의 조언이 혼란을 줄 수 있습니다. v1으로 Yarn을 배운 팀원은 명령어 하나로 모든 것을 전역적으로 삭제할 수 있다고 생각할 수 있습니다. 하지만 Berry에서는 다음과 같은 관점으로 생각해야 합니다. 범위(scope).
모바일과 웹 파이프라인에서 서로 다른 빌드 결과물을 다루고 있다면, 이러한 범위 중심의 사고방식은 패키지 관리 외의 영역에도 적용됩니다. 다음은 빌드 유형별 비교입니다 환경에 대한 가정이 디버깅 과정에 영향을 미칠 수 있다는 점을 상기시켜 줍니다.
명령어 상세 내용을 살펴보기 전에 시각적 설명을 먼저 확인하세요:
Berry에서 중요한 명령어들
최신 Yarn 문서에 따르면 yarn cache clean 삭제하는 기능입니다. 공유 캐시 파일들을또한 다음 두 가지 중요한 스위치를 제공합니다: 현재 Yarn cache clean 명령어 레퍼런스에서:
yarn cache cleanYarn의 공유 캐시 파일을 삭제합니다.yarn cache clean --mirror로컬 프로젝트 캐시 대신 글로벌 캐시를 비웁니다.yarn cache clean --all글로벌 캐시 파일과 현재 프로젝트의 로컬 캐시 파일을 모두 삭제합니다.
이를 통해 Yarn v1보다 더 의도적인 워크플로우를 구성할 수 있습니다.
| 목표 | 명령어 |
|---|---|
| 기본 공유 캐시 범위 삭제 | yarn cache clean |
| 글로벌 미러 캐시 대상 | yarn cache clean --mirror |
| 로컬 및 글로벌 캐시 파일 전체 초기화 | yarn cache clean --all |
사용하세요: --all “완전히 처음부터 다시 시작”하는 것과 가장 유사한 효과를 원할 때 사용하세요. --mirror 문제가 글로벌 캐시 레이어에 있다고 판단되지만, 프로젝트 전체를 삭제하고 싶지 않을 때 사용하세요.
결정 포인트: Berry에서는 잘못된 범위를 선택하는 것이 캐시 삭제가 “아무 효과가 없는” 주요 원인 중 하나입니다.
이것이 실질적인 차이점입니다. Yarn Classic은 기본적으로 범위가 넓었지만, Berry는 설계 단계부터 명시적입니다.
CI/CD 및 Docker를 위한 Yarn 캐시 베스트 프랙티스
CI/CD에서 Yarn 캐시를 무작정 삭제하는 것은 대개 실수입니다. 상태를 제거하니 안전해 보일 수 있지만, 실제로는 파이프라인의 속도와 재현성을 유지해 주는 핵심 상태까지 지워버리는 경우가 많기 때문입니다.
더 중요한 질문은 이것입니다: 정확히 무엇을 캐싱하고 있으며, 무엇을 복구하고 있는가?
파이프라인에서 캐시를 삭제하는 것이 왜 잘못된 선택인 경우가 많은가
CircleCI의 한 논의에서는 많은 팀이 실제 프로젝트에서 겪는 실패 패턴을 보여줍니다. 병목 현상이 오래된 패키지 아카이브 때문이 아니었기에, 캐시를 정리해도 설치 속도는 개선되지 않았습니다. 원인은 fetch 및 link 동작, 캐시 디렉토리 불일치, 그리고 캐시 세트에 포함되지 않은 node_modules 경로 문제였습니다. 해당 CircleCI Yarn 캐싱 스레드에 설명된 바와 같습니다..
이것이 중요한 이유는 CI 시스템이 '설치가 느림' 또는 '의존성 단계가 불안정함'과 같은 모호한 증상 뒤에 근본 원인을 숨기는 경우가 많기 때문입니다. 개발자는 캐시를 삭제하고 다시 실행해 보지만, 유의미한 개선은 얻지 못합니다.
흔히 발생하는 파이프라인 실수:
- 잘못된 디렉토리를 캐싱하는 경우: 복구(restore) 단계는 완료되었지만, Yarn이 복구된 위치를 사용하지 않는 경우.
- 워크스페이스 경로 무시: 루트 의존성은 복원되지만 워크스페이스 설치 작업은 여전히 다시 링크해야 할 수 있습니다.
- Docker 레이어를 잘못된 순서로 빌드하는 경우: 소스 code 복사로 인해 의존성 레이어가 무효화되어, 매번 패키지 설치가 다시 실행됩니다.
CI에서 잘못된 설정으로 인한 캐시 미스는 손상된 캐시와 매우 비슷해 보입니다.
자동화된 환경에서 모바일 앱을 빌드한다면, 여기서 릴리스 툴링도 등장합니다. 팀들은 종종 GitHub Actions나 CircleCI를 배포 및 업데이트 시스템과 함께 사용합니다. 이 더 넓은 워크플로우에서 한 가지 옵션은 Capacitor 앱을 위한 Capgo의 CI/CD 설정패키지 매니저 및 빌드 캐시 전략과 함께.
더 나은 CI 및 Docker 접근 방식
캐시 무효화는 감정이 아닌 의도에 따라 사용하세요.
CI에서 신뢰할 수 있는 패턴은 다음과 같습니다:
- 의존성 상태 기반 캐싱: 캐시 키를
yarn.lock및 관련 Yarn 설정 파일에 연결하세요. - 설치 전에 복구: 복구된 경로가 해당 환경에서 Yarn이 사용할 경로와 일치하는지 확인하세요.
- 일관되게 설치: immutable 설정에서는 lockfile 정확성을 강제하는 install 모드를 사용하세요.
- 실제 변경 시 무효화: Yarn 버전 변경, lockfile 업데이트 또는 cache-path 변경은 캐시를 다시 빌드할 좋은 이유입니다.
Docker에서도 원리는 비슷합니다:
- 의존성 매니페스트를 먼저 복사하세요: 가능하면 의존성 설치 레이어를 애플리케이션 소스와 분리하세요.
- 이미지 빌드 시 불필요한 정리 작업은 피하세요: 동일한 빌드 내에서 캐시를 삭제하면 유용한 레이어 재사용 기회를 놓칠 수 있습니다.
- 사용자 권한을 명확히 설정하세요: root 권한으로 생성된 캐시 디렉토리는 나중에 non-root 런타임 사용자의 설치 실패를 유발할 수 있습니다.
다음 결정 테이블을 참고하세요:
| 시나리오 | 권장 조치 yarn cache clean |
|---|---|
| 복구 후 CI 설치 속도가 느림 | 캐시 경로 및 복구 순서 확인 |
| Workspaces의 재연결(relink) 작업이 여전히 많음 | 관련 workspace 설치 아티팩트를 캐싱 |
| Docker 재빌드 시 설치 과정이 반복됨 | 의존성 파일 주변으로 레이어 순서 재배치 |
| 의존성 변경 후 빌드가 꼬였을 때 | 캐시 키를 무효화하고 깨끗하게 다시 빌드하세요 |
CI에서 Yarn clear cache는 오래된 캐시가 확실한 원인일 때만 사용하세요. 대부분의 경우 더 나은 캐시 설계가 근본적인 해결책입니다.
자주 발생하는 Yarn 캐시 오류 해결하기
가장 짜증 나는 캐시 버그는 캐시를 삭제해도 남아있는 버그입니다. 특정 부분을 정리하고 다시 설치해도 Yarn이 여전히 옛날 패키지를 가져올 때가 있죠. 이럴 땐 레지스트리가 잘못되었거나 lockfile에 문제가 생겼다고 생각하기 쉽습니다.
Yarn의 기록된 이슈를 보면 왜 이런 일이 발생하는지 알 수 있습니다. 개발자들은 다음과 같은 현상을 보고했습니다. yarn cache clean <package-name> 에 오래된 복사본을 남겨둘 수 있으며 cache/.tmp이로 인해 해당 임시 디렉토리가 삭제되거나 전체 클린업을 실행하기 전까지는 계속 오래된 버전을 사용하게 됩니다. 이는 다음 내용에서 다루는 의 오래된 캐시 아티팩트에 관한 Yarn 이슈와 관련이 있습니다. .tmp.
부분적인 클린업 후에도 패키지가 남아있을 때
교훈은 간단합니다. 부분적인 클린업만으로는 부족할 수 있습니다.
단순한 손상이 아니라 버전이 예전 상태로 머물러 있는 것이 의심된다면, 다음 순서를 따르세요:
- 가장 먼저 기본적인 사항부터 확인하세요: 현재 디버깅 중인 패키지 버전과 소스가 맞는지 확인합니다.
- 특정 패키지만 클린하는 것을 너무 믿지 마세요: 타겟팅된 정리 작업은 임시 아티팩트를 남길 수 있습니다.
- 전체 캐시 삭제로 단계를 높이세요: 이전 버전이 계속 남아 있다면, 더 넓은 범위의 캐시를 정리해야 합니다.
- 임시 캐시 경로를 직접 확인하세요: 이전 설정 방식에서는,
cache/.tmp이 해결의 핵심일 수 있습니다.
패키지가 계속 옛날 아티팩트로 연결된다면, 특정 패키지 클린에 실패한 후 가장 먼저 임시 캐시 파일을 확인해 볼 것입니다.
캐시 문제처럼 보이는 권한 및 환경 문제
모든 “캐시 에러”가 캐시 콘텐츠 문제인 것은 아닙니다.
Docker, 멀티 유저 Linux 시스템 또는 CI runner 환경에서는 Yarn을 실행하는 프로세스와 캐시 디렉토리의 소유자가 달라 권한 오류가 발생할 수 있습니다. 이 경우 소유권 문제를 해결하기 전까지는 캐시를 삭제해도 도움이 되지 않습니다. 가장 실질적인 해결책은 Yarn을 올바른 사용자로 실행하거나, 재설치 전에 디렉토리 소유권을 복구하는 것입니다.
이런 문제는 환경마다 설치 실패 여부가 달라 마치 캐시가 꼬인 것처럼 보일 때가 많습니다. 이는 패키지 문제가 아니라 운영 환경의 문제입니다.
Yarn 캐시 삭제에 관한 자주 묻는 질문(FAQ)
Yarn 캐시를 지워도 안전할까요?
네, 안전합니다. 일반적인 개발 과정에서 캐시를 삭제하는 것은 애플리케이션 소스 코드가 아닌 캐시된 패키지 아티팩트를 제거하는 것이기 때문입니다. Yarn은 다음 install 시 필요한 파일을 다시 가져올 수 있습니다.
다만 시간이 더 걸릴 수 있다는 점을 고려해야 합니다. 캐시를 비우면 다음 install 시 평소보다 더 많은 데이터를 다운로드하거나 빌드해야 할 수도 있습니다.
얼마나 자주 해야 할까요?
필요한 이유가 있을 때만 수행하세요.
문제가 없는 프로젝트에서 yarn clear cache를 정기적으로 실행할 필요는 없습니다. 습관적으로 모든 워크플로우에 포함시키면 로컬 install 속도가 느려지고 CI 캐싱 효율도 떨어집니다. 의존성이 꼬였거나, 설치가 손상된 것 같을 때, 또는 디버깅 중 의도적인 리셋이 필요할 때만 사용하세요.
프로덕션 빌드에 영향을 줄까요?
직접적인 영향은 없습니다. 로컬이나 CI의 캐시를 삭제한다고 해서 이미 커밋한 애플리케이션 code이 변경되지는 않습니다.
이 작업이 바꾸는 것은 빌드를 준비하는 환경입니다. 만약 프로덕션 파이프라인이 캐시된 설치 아티팩트에 의존하고 있다면, 이를 삭제할 경우 빌드 속도가 느려지거나 숨겨진 재현성 문제가 드러날 수 있습니다. 이는 트러블슈팅 시에는 유용하지만, 명확한 이유 없이 릴리스 스크립트에 무분별하게 추가해서는 안 됩니다.
따라야 할 가장 간단하고 실용적인 규칙은?
문제 상황에 맞는 최소한의 정리 작업만 수행하세요.
로컬 디버깅 시에는 해당 프로젝트에서 Yarn이 사용하는 캐시 범위부터 확인하세요. CI 및 Docker 환경에서는 캐시를 삭제하기 전에 먼저 캐시 설계를 점검해야 합니다. 특정 패키지 정리로 해결되지 않는다면, Yarn 자체의 문제로 단정하기 전에 임시 아티팩트나 환경 불일치를 먼저 의심해 보세요.
팀에서 Capacitor 앱을 배포 중이며, 의존성이나 빌드 이슈 이후 더 깔끔한 릴리스 파이프라인이 필요하다면, Capgo 스토어 심사를 기다리지 않고 JavaScript 및 에셋 업데이트를 전달할 수 있는 옵션입니다. 이를 통해 빌드 및 롤아웃 프로세스를 패키지 캐시 트러블슈팅과 분리하여 유지할 수 있습니다.
