Mac에서 npm 캐시를 안전하게 비우는 방법

npm 캐시와 node_modules 구분하기

npm 캐시는 여러 프로젝트에서 재사용하는 다운로드 데이터이며 macOS의 기본 위치는 ~/.npm이지만 설정으로 바꿀 수 있습니다. node_modules는 각 프로젝트에 설치된 의존성 트리입니다. package.json과 package-lock.json도 캐시가 아니라 같은 의존성 해석 결과를 재현하는 데 필요한 입력입니다. 기존 npm-shrinkwrap.json 역시 프로젝트 파일이지만 npm v12는 이 파일을 읽지 않으므로, npm v12로 재설치하기 전에 같은 형식의 파일 이름을 package-lock.json으로 바꿔야 합니다.

사용 중인 캐시를 측정하고 검증하기

~/.npm이 존재한다고 해서 현재 사용하는 캐시라고 단정하지 마세요. npm config get cache가 출력한 정확한 경로를 따옴표로 묶어 du로 측정하고 npm cache verify로 인덱스와 콘텐츠 무결성을 검사하면서 불필요한 데이터를 정리하세요. npm 캐시는 자체 복구를 전제로 하므로 일반적인 유지 관리에는 verify만으로 충분할 수 있습니다. ERESOLVE, 인증, 404, 프록시, Node.js 엔진, 네이티브 빌드, postinstall 문제는 유효한 캐시를 삭제해도 해결되지 않습니다.

1. npm --version과 npm config get cache를 실행하고 출력된 경로가 프로젝트가 아니라 캐시인지 확인합니다.
2. 출력된 정확한 경로를 따옴표로 묶어 du -sh의 인수로 전달하고 macOS의 여유 공간도 기록합니다.
3. 실행 중인 npm install, npm ci, npm exec, npm publish를 종료한 뒤 npm cache verify를 실행하고 요약과 오류를 보관합니다.
4. npm cache verify 이후에도 공간 확보가 필요하고 재다운로드할 수 있음을 확인한 경우에만 npm cache clean --force를 실행합니다.
5. npm cache verify와 측정을 다시 수행한 뒤 원래 lockfile을 유지한 대표 프로젝트에서 설치, 빌드, 테스트를 실행해 검증합니다.

확인하지 않은 경로를 rm -rf에 넘기지 마세요. 이 절차에는 수동 재귀 삭제가 필요하지 않습니다. 캐시와 lockfile을 함께 삭제하면 설치 오류의 원인을 비교할 근거도 잃게 됩니다.

필요할 때만 --force로 캐시 비우기

측정한 캐시가 크고 확보할 공간의 가치가 재사용 가치보다 높을 때만 npm cache clean --force를 실행하세요. 이 명령은 설정된 캐시를 비우므로 다음 설치나 npm ci에서 파일을 네트워크로 다시 받아야 합니다. 사설 레지스트리, Git 호스트, 프록시 또는 인터넷에 접근할 수 없거나 필요한 패키지가 배포 원본에서 사라졌다면 복구가 실패할 수 있습니다. force를 npm의 영구 설정으로 두지 말고 이 명령에만 사용하세요.

의존성 그래프를 바꾸지 않고 결과 확인하기

정리 후 npm config get cache와 du로 같은 위치를 다시 측정하고 원래 package.json과 lockfile을 바꾸지 않은 채 대표 프로젝트의 설치, 빌드, 테스트를 실행하세요. 같은 오류가 다시 나타나면 캐시 삭제를 반복하지 말고 저장한 오류, npm과 Node.js 버전, 레지스트리 설정을 진단합니다. AskClean의 npm 항목은 기본 ~/.npm 전체를 대상으로 하므로, 사용자 지정 캐시는 npm 자체 명령으로 확인해야 합니다.

삭제 판단과 복구 비용

npm이 실제로 사용하는 다운로드 캐시를 찾아 측정하고 먼저 무결성을 검증한 뒤, 필요한 경우에만 비우면서 node_modules와 프로젝트 파일은 보호합니다.

자주 묻는 질문