できない.dev

Vite で HMR (Hot Module Replacement) が反映されない

Vite の HMR は ESM 経由のモジュール置換で動く。
ファイル監視・WebSocket 接続・Fast Refresh の更新境界・副作用モジュールのいずれかでつまずくと反映されない。
DevTools の Console と Network タブで状態を確認し、原因を順に切り分ける。

公開: 更新:

症状できない
tail -n 1 vite.log
1:06:22 AM [vite] (client) page reload theme.js

2026-10-19 に node:22(Vite 8.3.4 / Node.js 22.23.3) で実際に打って取った出力。検証環境の詳細

要約

Vite の HMR が反映されない原因は、次のいずれかである。
(1) ファイル監視が変更を拾えていない。
(2) ブラウザと dev server の WebSocket が確立できていない。
(3) React Fast Refresh の更新境界が認識されない。
(4) 副作用モジュールを HMR で扱おうとしている。
切り分けは、ブラウザ DevTools の Console と Network タブで client (WebSocket) の状態と HMR ログを確かめるところから始める。

実行例

node:22 のコンテナで dev server を起動し、main.js が読み込み時に呼んでいる theme.js を編集すると、更新を受け止める処理が無いためログは page reload theme.js と、ページ全体の再読み込みになった。
main.js に import.meta.hot.accept を書いてから同じ編集をすると、ログは hmr update /main.js に変わった。

$ tail -n 1 vite.log
1:06:22 AM [vite] (client) page reload theme.js
$ tail -n 1 vite.log
1:06:24 AM [vite] (client) hmr update /main.js

— 2026-10-19 時点の出力

検証環境Node.js 22.23.3 / npm 10.9.9 / Python 3.11.2 / 2026-10-19 検証(ほか 2 件)
検証日
実行環境
node:22 Debian GNU/Linux 12 (bookworm)
バージョン
  • Node.js 22.23.3
  • npm 10.9.9
  • Python 3.11.2
  • Git 2.39.5
  • Vite 8.3.4

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. ポーリングモードを有効にする

Docker / WSL 環境では fs.watch (inotify) が動かないため、server.watch options(新しいタブで開く) でポーリングへ切り替える。

// vite.config.ts
import { defineConfig } from "vite";
 
export default defineConfig({
  server: {
    watch: { usePolling: true, interval: 300 },
  },
});

2. HMR の接続先を明示する

リバースプロキシや HTTPS 越しに dev server を見ている場合、ブラウザが繋ぎに行く先を server.hmr で固定する。

export default defineConfig({
  server: {
    hmr: { protocol: "wss", host: "dev.example.com", clientPort: 443 },
  },
});

3. Fast Refresh の規約に合わせる

React の Fast Refresh は「ファイルが関数コンポーネントだけを export する」前提で更新境界を切る。
定数やユーティリティ関数を同居 export していると full reload に落ちる。

// NG: コンポーネントと定数が同居
export const COLORS = ["red", "blue"];
export default function Button() { /* ... */ }
 
// OK: 定数は別ファイルへ移し、Button.tsx は default export のみ

4. 副作用モジュールは HMR API を使う

グローバル状態を触るコードでは HMR API(新しいタブで開く) を直接呼び、再評価後の処理を自前で書く。

import { applyTheme } from "./theme";
 
applyTheme();
 
if (import.meta.hot) {
  import.meta.hot.accept("./theme", (m) => m?.applyTheme());
}

よくある原因

  1. ファイル監視が変更を拾えていない。
    Docker / WSL2 / ネットワークマウント上では、fs.watch がホスト側の変更を検知できない。
  2. WebSocket の接続に失敗している。
    HTTPS リバースプロキシ越しやポート転送越しの接続、host 指定の不一致があると、client 接続が確立しない。
  3. Fast Refresh の更新境界から外れている。
    React コンポーネントが named export のみか、同一ファイルから非コンポーネントも export している。
  4. 副作用モジュールを HMR で置き換えようとしている。
    グローバル CSS の適用やシングルトンの初期化などは、置換しても効果がない。