Vite에서 HMR 동작 문제 해결 가이드

서론: 겪고 있는 문제

Vite로 프로젝트를 마이그레이션한 후, 주석을 변경하거나 단순히 콘솔 로그를 추가/삭제하는 사소한 작업에도 전체 페이지가 새로고침되는 문제가 발생했습니다. Vite의 HMR(Hot Module Replacement) 기능은 코드 변경 시 필요한 모듈만 업데이트하여 애플리케이션 상태를 유지하며 빠르게 변경 사항을 반영해야 하지만, 의도와 다르게 페이지 전체가 리로드되는 상황이었습니다. 이 문제를 해결하기 위해 원인을 파악하고 단계적으로 해결 방안을 적용했습니다.

최종적으로는 마지막 업데이트로 해결 하였습니다.

1. Vite 설정 파일 점검 및 HMR 설정 세부 조정

초기 HMR 설정

먼저, Vite 설정 파일(vite.config.js)에서 HMR 설정을 확인하고 기본적으로 활성화된 오류 오버레이를 비활성화하였습니다.

// vite.config.js
import { defineConfig } from "vite";

export default defineConfig({
  server: {
    hmr: {
      overlay: false, // 브라우저 오버레이 비활성화
    },
  },
});

HMR 세부 설정 조정

HMR의 동작을 더욱 세밀히 조정하여, 불필요한 새로고침이나 연결 문제가 발생하지 않도록 추가 설정을 진행했습니다.

// vite.config.js
import { defineConfig } from "vite";

export default defineConfig({
  server: {
    hmr: {
      overlay: false, // 브라우저 오버레이 비활성화
      protocol: 'ws', // 웹소켓 프로토콜 사용
      timeout: 30000, // HMR 연결 시간 제한
    },
    watch: {
      ignored: ['**/node_modules/**', '**/.git/**', '**/dist/**'], // 감시 제외 대상 설정
    },
  },
});

---

주요 옵션 설명

1. overlay: false

• 기능: HMR 오류 발생 시 브라우저 화면에 표시되는 빨간색 오류 오버레이를 비활성화합니다.
• 설명: 오류를 개발자 도구(콘솔)에만 기록하며, UI 개발 중 화면을 방해하지 않습니다.

2. protocol: 'ws'

• 기능: HMR에서 사용할 통신 프로토콜을 지정합니다.
• 설명: 기본적으로 ws(WebSocket)를 사용하며, HTTPS 환경에서는 보안을 위해 wss(WebSocket Secure)를 사용할 수도 있습니다.

3. timeout: 30000

• 기능: HMR 연결이 끊겼을 때 재시도하기 전까지 대기하는 시간을 지정합니다.
• 설명: 30초(30000ms)로 설정되며, 너무 짧으면 성능 저하, 너무 길면 재연결 지연이 발생할 수 있습니다.

4. watch.ignored

• 기능: 특정 파일이나 디렉토리를 파일 변경 감시에서 제외합니다.
• 설명:
  • `/node_modules/`: 외부 의존성 파일 제외.
  • `/.git/`: Git 관련 파일 제외.
  • `/dist/`: 빌드 결과물 디렉토리 제외(개발 환경과 무관한 변경).

---

통합된 설정 요약

위 설정을 통해:

• 브라우저 오버레이가 비활성화되어 작업 흐름을 방해받지 않습니다.
• 파일 변경 감시에서 필요 없는 디렉토리를 제외하여 개발 서버 성능이 최적화됩니다.
• HMR 연결 안정성이 향상되어 불필요한 새로고침이 줄어듭니다.

2. 캐시 문제 해결

HMR 문제는 종종 브라우저나 Vite의 캐시와 관련이 있을 수 있습니다. 모든 캐시를 삭제한 후 다시 설치하여 문제를 해결했습니다.

캐시 삭제 명령어

rm -rf node_modules/.vite
rm -rf node_modules
npm install

브라우저 캐시 삭제 방법

1. 브라우저 개발자 도구 열기 (F12).
2. "애플리케이션" 탭으로 이동.
3. "사이트 데이터" 또는 "캐시 삭제" 버튼 클릭.

---

3. 최신 버전 업데이트

Vite와 관련 플러그인들이 최신 버전인지 확인하고 업데이트를 진행했습니다. 최신 버전은 알려진 버그가 수정된 상태일 가능성이 높습니다.

업데이트 명령어

npm update

---

요약 및 결론

위 단계를 따라 설정을 점검하고 문제를 해결하면, Vite의 HMR 기능이 정상적으로 작동하여 다음과 같은 결과를 얻을 수 있습니다:

• HMR 설정 최적화: 불필요한 페이지 새로고침 제거.
• 개발 효율성 향상: 주석 변경이나 콘솔 수정 시에도 빠르게 변경 사항 확인.
• 성능 개선: 파일 감시 제외 및 캐시 삭제로 불필요한 리소스 소모 방지.

핵심 조치 요약

1. HMR 오버레이 비활성화
2. 브라우저 및 Vite 캐시 삭제
3. HMR 설정 세부 조정
4. 최신 버전으로 업데이트