VScode에서 Vite Hot Reloading 설정 방법

8월 06, 2025

Vite는 기본적으로 Hot Module Replacement, 줄여서 HMR을 지원합니다.
일반적인 개발 환경에서는 별도의 설정 없이도 파일을 저장하면 브라우저에 변경 사항이 자동으로 반영됩니다.

하지만 WSL2, Docker, DevContainer 같은 환경에서는 파일 변경 감지가 제대로 동작하지 않아 Hot Reload가 안 되는 경우가 있습니다.


1. 일반적인 Vite 환경에서는 별도 설정이 필요하지 않음

Vite 프로젝트를 생성한 뒤 개발 서버를 실행하면 기본적으로 HMR이 활성화됩니다.

npm run dev

또는 Yarn을 사용한다면 다음 명령어를 실행합니다.

yarn dev

개발 서버가 실행된 상태에서 파일을 수정하고 저장하면 브라우저가 자동으로 변경 사항을 반영합니다.

즉, 일반적인 로컬 개발 환경에서는 별도의 추가 설정 없이 Hot Reload가 정상적으로 동작합니다.

2. WSL2, Docker, DevContainer 환경에서 Hot Reload가 안 되는 이유

Hot Reload 문제가 자주 발생하는 환경은 다음과 같습니다.

  • WSL2
  • Docker
  • DevContainer
  • bind mount를 사용하는 개발 환경

예를 들어 WSL2에서 Vite 개발 서버를 실행하고, Windows 쪽 VSCode에서 파일을 수정하는 경우 파일 변경 이벤트가 제대로 전달되지 않을 수 있습니다.

Docker나 DevContainer 환경에서도 bind mount로 연결된 파일 시스템을 사용할 때 비슷한 문제가 발생할 수 있습니다.

이 경우 Vite가 파일 변경을 감지하지 못하기 때문에 코드를 수정해도 브라우저가 자동으로 갱신되지 않습니다.

3. 해결 방법: usePolling 옵션 추가하기

가장 간단한 해결 방법은 Vite 설정 파일에 server.watch.usePolling 옵션을 추가하는 것입니다.

vite.config.js 또는 vite.config.ts 파일을 열고 다음과 같이 설정합니다.

Vue 프로젝트 예시

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  server: {
    watch: {
      usePolling: true, // 파일 변경 감지를 polling 방식으로
    },
  },
})

React 프로젝트 예시

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    watch: {
      usePolling: true, // 파일 변경 감지를 polling 방식으로
    }, 
  },
})

usePolling: true는 파일 변경을 이벤트 기반으로 감지하는 대신, 일정 주기로 파일 변경 여부를 확인하는 방식입니다.

따라서 WSL2, Docker, DevContainer처럼 파일 변경 이벤트가 제대로 전달되지 않는 환경에서도 Hot Reload가 동작할 가능성이 높아집니다.

4. usePolling 사용 시 주의할 점

usePolling 옵션은 Hot Reload 문제를 해결하는 데 효과적이지만, 파일 변경 여부를 계속 확인하기 때문에 CPU 사용량이 증가할 수 있습니다.

따라서 가능하다면 다음과 같은 방식도 함께 고려하는 것이 좋습니다.

  • WSL2 내부에서 VSCode 실행하기
  • 컨테이너 내부에서 직접 파일 수정하기
  • DevContainer에서 bind mount 대신 named volume 사용하기

특히 DevContainer를 사용하는 경우 VSCode의 다음 기능을 사용하면 Hot Reload가 더 안정적으로 동작할 수 있습니다.

Dev Containers: Clone Repository in Named Container Volume...

이 방식은 프로젝트를 컨테이너 내부의 named volume에 복제하기 때문에 bind mount에서 발생하는 파일 감지 문제를 줄일 수 있습니다.

5. 그래도 Hot Reload가 안 된다면 확인할 것들

설정을 추가했는데도 Hot Reload가 동작하지 않는다면 아래 항목들도 함께 확인해보는 것이 좋습니다.

5-1. import 경로의 대소문자 확인

파일명과 import 경로의 대소문자가 다르면 운영체제나 파일 시스템에 따라 문제가 발생할 수 있습니다.

예를 들어 실제 파일명이 Header.vue인데 다음과 같이 import하고 있다면 문제가 될 수 있습니다.

import Header from './header.vue'

이 경우 실제 파일명과 동일하게 수정해야 합니다.

import Header from './Header.vue'

5-2. 파일 저장 여부 확인

Hot Reload는 기본적으로 파일이 저장된 뒤 동작합니다.

자동 저장을 사용하지 않는다면 파일을 수정한 뒤 반드시 저장해야 합니다.

Windows / Linux: Ctrl + S
macOS: Cmd + S

5-3. 개발 서버 재시작

vite.config.js 또는 vite.config.ts 파일을 수정했다면 개발 서버를 재시작하는 것이 좋습니다.

npm run dev

설정 파일 변경 사항은 개발 서버를 다시 실행해야 제대로 반영되는 경우가 많습니다.

댓글 쓰기 · 수정

0 댓글