[TroubleShooting] Next.js Fast Refresh 오류 해결

💥문제 요약 (Problem)

Next 프로젝트 개발 중, 아래와 같은 Fast Refresh 오류 메시지가 나타났다.

○ Compiling /404 ...
✓ Compiled /404 in 850ms (461 modules)
GET /_next/static/webpack/9720620fcfe680fa.webpack.hot-update.json 404 in 1811ms
⚠ Fast Refresh had to perform a full reload. Read more: https://nextjs.org/docs/messages/fast-refresh-reload

이 메시지는 개발 중 Hot Module Replacement(HMR)가 실패하여 전체 페이지를 리로드했다는 뜻이다.
치명적인 오류는 아니지만, 반복될 경우 개발 효율에 영향을 줄 수 있다.

🔍 원인 분석 (Root Cause)

이 오류는 보통 Next.js 개발 환경에서 다음과 같은 경우에 발생한다.

• HMR 캐시가 꼬였거나, 동적으로 import한 모듈 변경이 반영되지 않는 경우
• 빌드 캐시 혹은 node_modules 내부 의존성 문제
• 너무 자주 혹은 조건부로 dynamic import가 변경되는 경우

🌟 즉, Fast Refresh의 정상적인 대처 과정이며 프로덕션 빌드에는 영향을 미치지 않는다.

📌 HMR(Hot Module Replacement)이란,

HMR은 코드 변경 시 전체 페이지를 새로고침하지 않고, 변경된 모듈만 교체해 상태를 유지한 채로 업데이트할 수 있도록 돕는 기능이다.
Next.js는 이를 위해 Fast Refresh를 사용하며, 실패 시 전체 리로드가 발생한다.

💡 해결 방법 (Solution)

1️⃣ 개발 서버 재시작

• 구조 변경, dynamic import 추가 등으로 HMR 캐시가 꼬일 수 있다.
• 가장 간단한 해결책은 서버를 재시작하는 것이다.

# 서버 재시작
Ctrl + C  # 개발 서버 종료
pnpm dev  # 다시 실행

2️⃣ 의존성/빌드 캐시 재설정

• node_modules 또는 .next 빌드 캐시 문제가 원인일 수 있다.
• pnpm 관련 캐시도 정리하는 것을 권장한다.

# 의존성 및 빌드 캐시 제거
rm -rf node_modules .next
rm pnpm-lock.yaml
pnpm store prune        # 사용하지 않는 캐시 정리

# (선택) 글로벌 캐시까지 완전히 정리할 경우
pnpm store clear        # ⚠️ 모든 프로젝트 캐시 삭제

# 의존성 재설치
pnpm install

💡 Windows에서 PowerShell을 사용하는 경우, 관리자 권한으로 실행 권장한다.

Remove-Item -Recurse -Force .\node_modules\
Remove-Item -Force .\pnpm-lock.yaml

✅ 명령어 실행 후 PC를 재부팅하면 환경 정리가 더 확실해진다.

3️⃣ dynamic import 시점 최적화

• 조건부 dynamic import()나 빈번한 변경은 HMR을 불안정하게 만들 수 있음
• 렌더 조건이 복잡한 경우, dynamic import를 최소화하거나 구조를 단순화할 것

// 조건부 dynamic import 예시 (주의 필요)
const Component = condition
  ? dynamic(() => import('./ComponentA'))
  : dynamic(() => import('./ComponentB'));

• ⚠️ 위와 같은 패턴은 HMR 시스템이 모듈 트리를 추적하기 어렵게 만든다.

4️⃣ 공식 문서 참고

• Next.js 공식 문서 : Fast Refresh had to perform a full reload

🛡️ 이 메시지는 개발 환경에서만 발생하며,
프로덕션 빌드 (pnpm build)에서는 Fast Refresh 기능이 작동하지 않기 때문에 전혀 영향이 없다.