개발/FRONT

npm cache 때문에 수정이 적용되지 않을 때 해결방법 npmcache 삭제

Hdev&Shoes 2025. 12. 23. 21:19
728x90

 

프로젝트 코드를 수정했는데도 번들에 반영되지 않거나, 이전 번들이 계속 남아 있는 경우가 있다. 대부분은 npm 캐시, lock 파일, node_modules 잔여물이 원인이다. 이 글에서는 “수정이 적용되지 않는 현상”을 빠르게 해결하고, 재발을 막는 방법을 정리한다.

1. 왜 수정이 반영되지 않을까? (원인 분석)

수정 사항이 번들에 반영되지 않는 대표 원인은 다음과 같다.

  • npm 캐시에 남은 오래된 아티팩트: 이전 빌드 결과가 캐시에 남아 새 빌드에 섞임
  • node_modules 잔여물: 버전 변경/설정 변경 후에도 기존 모듈이 남아 동작
  • lock 파일과 실제 설치본 불일치: package-lock.json 또는 npm-shrinkwrap.json과 설치본이 어긋남
  • 빌드 결과물 캐시: Next.js/.next, React/Vite의 dist, Storybook의 static 등 이전 산출물이 재사용

2. 빠른 해결 절차 (명령어 순서)

아래 순서대로 실행하면 대부분의 “수정이 반영되지 않는” 문제를 해결할 수 있다.

2.1 npm 캐시 정리

npm cache clean --force

캐시를 완전히 비워서 오래된 패키지 아티팩트가 다시 사용되지 않도록 한다.

2.2 node_modules 폴더 삭제

rm -rf node_modules

설치된 모듈을 전부 삭제해, lock 파일 기준으로 새로 설치하게 만든다. (Windows는 rmdir /s /q node_modules)

2.3 빌드 산출물 정리

# 프로젝트 종류에 따라 필요한 폴더 삭제
rm -rf dist build .next out storybook-static

2.4 의존성 재설치

npm install

2.5 새로 빌드 / 시작

npm run build
npm run start   # 또는 npm run dev

새로운 의존성과 깨끗한 빌드 산출물로 실행해 수정 사항이 반영됐는지 확인한다.

3. 재발 방지 체크리스트

  • 캐시 삭제 루틴을 스크립트화: "clean": "rm -rf node_modules dist build .next out && npm cache clean --force"
  • lock 파일 일관성 유지: 팀 모두 동일한 npm 버전 사용, lock 파일을 항상 커밋
  • CI에서도 깨끗한 설치: CI 파이프라인에 npm ci 사용 (lock 기반, 깨끗한 설치)
  • 로컬 캐시가 의심될 때: npm cache verify 로 무결성 확인, 필요하면 clean --force
  • 빌드 산출물 분리: dist/build/.next/out 등을 git ignore로 관리해 오래된 산출물이 커밋되지 않도록 한다.
✅ 핵심 요약:
  • 캐시/설치본/빌드 산출물을 한 번에 지우고 새로 설치/빌드한다.
  • 캐시 정리: npm cache clean --force → rm -rf node_modules → npm install
  • 빌드 산출물 삭제: rm -rf dist build .next out storybook-static
  • 재발 방지: 공통 clean 스크립트, npm ci 활용, lock 파일 일관성 유지

 

 

카카오톡 오픈 채팅 링크

https://open.kakao.com/o/seCteX7h

 

728x90