できない.dev

webpack-dev-server で変更が反映されない(HMR が効かない)

webpack-dev-server v4 以降は HMR が既定で有効なので、効かないときは設定を足すより先に切り分ける。
ファイル変更が検知されているか、置換を受け取るコード側が対応しているか、フルリロードに落ちていないかの 3 点を順に確認する。

公開: 更新:

症状できない
cat webpack.config.js
module.exports = {
  mode: "development",
  entry: "./src/index.js",
  devServer: { port: 8080, static: false },
};

2026-10-17 に node:20(webpack 5.112.0 / Node.js 20.20.2) で実際に打って取った出力。検証環境の詳細

要約

「保存しても画面が変わらない」とき、まず devServer.hot: true を足そうとしがちだが、DevServer の公式ドキュメント(新しいタブで開く) のとおり webpack-dev-server v4 以降では hot は既定で有効である。
HotModuleReplacementPlugin も自動で適用されるため、設定を足しても状況は変わらない。

切り分けるべきは 3 段階である。
ファイル変更が検知されているか、ビルドが成功しているか、そのうえで置換がブラウザ側に届いているか。
どこで止まっているかで対処が変わる。

<i> [webpack-dev-server] Project is running at:
<i> [webpack-dev-server] Loopback: http://localhost:8080/
webpack compiled successfully

保存しても compiled successfully が再度出ないなら、そもそも変更が検知されていない。

実行例

hot を足していない設定でも、ブラウザの代わりに置いた受信クライアントには最初から hot のメッセージが届いた。
バンドルに入っている src/index.js を保存すると、再ビルドされて invalid・hash・ok が届いた。
バンドルに入っていない src/index.html を保存しても、再ビルドも通知も起きなかった。
watchFiles に書くと、static-changed が届くようになった。

$ cat webpack.config.js
module.exports = {
  mode: "development",
  entry: "./src/index.js",
  devServer: { port: 8080, static: false },
};
$ npx webpack serve
<i> [webpack-dev-server] Project is running at:
<i> [webpack-dev-server] Loopback: http://localhost:8080/, http://[::1]:8080/
<i> [webpack-dev-server] On Your Network (IPv4): http://172.17.0.2:8080/
webpack 5.112.0 compiled successfully in 139 ms
$ sed -i s/v1/v2/ src/index.js
$ grep compiled dev.log
webpack 5.112.0 compiled successfully in 139 ms
webpack 5.112.0 compiled successfully in 13 ms
$ cat ws.log
{"type":"hot"}
{"type":"liveReload"}
{"type":"reconnect","data":10}
{"type":"overlay","data":true}
{"type":"hash","data":"3cb62f2eae8db6ffed85"}
{"type":"ok"}
{"type":"invalid"}
{"type":"hash","data":"22406e4988c8e1de4f6c"}
{"type":"ok"}
$ sed -i s/v1/v2/ src/index.html
$ grep -c compiled dev.log
2
$ cat ws.log
{"type":"hot"}
{"type":"liveReload"}
{"type":"reconnect","data":10}
{"type":"overlay","data":true}
{"type":"hash","data":"3cb62f2eae8db6ffed85"}
{"type":"ok"}
{"type":"invalid"}
{"type":"hash","data":"22406e4988c8e1de4f6c"}
{"type":"ok"}
$ cat webpack.config.js
module.exports = {
  mode: "development",
  entry: "./src/index.js",
  devServer: {
    port: 8080,
    static: false,
    watchFiles: ["src/**/*.html"],
  },
};
$ sed -i s/v2/v3/ src/index.html
$ cat ws2.log
{"type":"hot"}
{"type":"liveReload"}
{"type":"reconnect","data":10}
{"type":"overlay","data":true}
{"type":"hash","data":"77816579ae5c693d1155"}
{"type":"ok"}
{"type":"static-changed","data":"src/index.html"}

— 2026-10-17 時点の出力

検証環境Node.js 20.20.2 / npm 10.8.2 / Python 3.11.2 / 2026-10-17 検証(ほか 2 件)
検証日
実行環境
node:20 Debian GNU/Linux 12 (bookworm)
バージョン
  • Node.js 20.20.2
  • npm 10.8.2
  • Python 3.11.2
  • Git 2.39.5
  • webpack 5.112.0

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

解決策

1. どこで止まっているか見る

保存したときに次の順で確認する。
ターミナルに再ビルドのログが出るか、出たあとブラウザのコンソールに [HMR] の行が出るか。
前者で止まっていれば監視の問題、後者で止まっていれば配信・受け入れの問題である。

2. コンテナや仮想ドライブではポーリングに切り替える

// webpack.config.js
module.exports = {
  devServer: {
    watchFiles: {
      paths: ["src/**/*"],
      options: { usePolling: true, interval: 300 },
    },
  },
};

ポーリングは CPU を使うので、監視対象を必要な範囲に絞る。

3. バンドル外のファイルを監視対象に加える

devServer: {
  watchFiles: ["src/**/*.html", "templates/**/*"],
},

依存グラフに入らないファイルは、ここに書いて初めて再読み込みの対象になる(devServer.static で配信しているディレクトリは既定で監視されるので書かなくてよい)。

4. フルリロードへの取りこぼしを可視化する

devServer: {
  hot: "only",
},

'only' にすると、HMR が失敗したときにフルリロードへ落ちずにそのまま止まる。
「実は毎回リロードしていただけ」という状態に気づける。

5. プロキシ配下では接続先を明示する

devServer: {
  client: {
    webSocketURL: "ws://localhost:8080/ws",
  },
},

配信元と見えているホスト・ポートが違う構成では、これを指定しないと HMR の通信だけが繋がらない。

よくある原因

  1. 変更が検知されていない。
    Docker のバインドマウント、WSL 越しの Windows ファイルシステム、ネットワークドライブでは、ファイル変更のイベントがコンテナや Linux 側へ届かないことがある。
    このときは保存しても再ビルドのログが出ない。
  2. 監視対象外のファイルを編集している。
    バンドルに含まれない HTML テンプレートや静的ファイルは、依存グラフに入っていないため編集しても再ビルドされない。
    ただし devServer.static で配信しているディレクトリ(既定は public/)は static.watch が既定で有効なので、編集するとページ全体が再読み込みされる。
  3. 置換を受け取る実装が無い。
    HMR は、更新されたモジュールを受け入れる実装があって初めて差分置換になる。
    React Fast Refresh のような仕組みが入っていない素の構成では、受け入れ先が無いためフルリロードに落ちる。
  4. WebSocket が繋がらない。
    リバースプロキシや別ポート越しに開いていると、HMR の通信先が実際の配信元とずれて接続できない。
    このときはブラウザのコンソールに接続失敗が出る。
  5. ビルドが失敗している。
    型エラーや構文エラーで新しいバンドルが作られていない。
    ターミナルにエラーが出ていれば、画面が変わらないのは当然である。