npm을 사용하다 보면 Please run npm cache clean과 같은 이상한 오류 메시지를 만나는 경우가 있습니다. 이럴 때는 npm 캐시를 정리하거나 새로고침해야 할 수 있습니다.
가장 먼저 시도해 볼 수 있는 방법은 npm cache clean 명령어를 실행하는 것입니다.
npm 버전 5 이상에서는 "npm cache verify" 실행하기
다만 npm v5 이상을 사용 중이라면 상황이 조금 다릅니다. npm v5부터는 캐시가 자가 복구(self-healing)되도록 설계되었기 때문에, npm cache clean을 실행하면 아래와 같은 오류 메시지가 나타날 수 있습니다.
npm ERR! As of [email protected], the npm cache self-heals from corruption issues and data extracted from the cache is guaranteed to be valid. If you want to make sure everything is consistent, use 'npm cache verify' instead.
npm ERR!
npm ERR! If you're sure you want to delete the entire cache, rerun this command with --force.이 오류가 발생했다면 대신 npm cache verify 명령어를 실행해 보세요. 이 명령은 캐시의 무결성을 검증하고 손상된 데이터를 자동으로 정리해 줍니다.
node_modules 폴더 삭제 후 재설치
위 방법으로도 문제가 해결되지 않는다면, 프로젝트 내의 node_modules 폴더를 삭제한 뒤 npm install을 다시 실행해 보는 것도 좋은 방법입니다. 종종 캐시 문제가 아니라 프로젝트 자체의 의존성 설치 오류일 수 있기 때문입니다.
"npm cache clean --force"로 강제 삭제하기
npm cache clean과 npm cache verify 모두 작동하지 않고 캐시를 지울 수 없다면, 강제로 캐시를 삭제할 수 있습니다. 다음 명령어를 사용하세요.
npm cache clean --force 또는 축약형으로 npm cache clean -f
이 명령은 컴퓨터에 저장된 npm 캐시 전체를 강제로 삭제합니다. 단, 캐시가 모두 사라지기 때문에 이후 패키지 설치 시 다시 다운로드해야 한다는 점을 참고하세요.
npm cache clean은 정확히 어떤 역할을 할까?
npm으로 패키지를 설치하면, npm은 먼저 해당 패키지와 의존성들을 로컬 npm 캐시 폴더에 저장합니다. npm 공식 문서에 따르면 이 경로는 Posix 계열(macOS, Linux)에서는 ~/.npm, Windows에서는 %AppData%/npm-cache입니다.
그다음 npm은 캐시에 저장된 패키지들을 프로젝트의 node_modules 폴더에 실제로 설치합니다.
이후 동일한 패키지를 다시 설치할 때, npm은 매번 원격 저장소에서 다운로드하는 대신 로컬 캐시에서 바로 가져오기 때문에 설치 속도가 크게 빨라집니다.
그러나 서로 다른 버전의 의존성이 함께 설치되면서 충돌이 발생하면, 캐시가 손상될 수 있습니다. 이때 캐시를 삭제하면 npm에서 패키지를 처음부터 다시 받아와 깨끗한 상태로 설치할 수 있습니다.