Antigravity でホットリロード（HMR）が効かない問題の切り分けと修正手順

「保存しているはずなのにブラウザが更新されない」「HMR が一度だけ効いて、その後沈黙してしまう」— Antigravity で Next.js や Vite を扱うとき、誰もが一度はぶつかる現象ではないでしょうか。私自身、Dolice Labs の 4 サイトを日々開発していて、AI エージェントに大きな修正を任せた直後に HMR が止まる場面を何度も経験しました。

HMR が効かない問題は、原因が「ファイルウォッチャー」「ポートとプロキシ」「ビルドツールの設定」「Antigravity 固有の挙動」の 4 領域にまたがるため、勘で直そうとすると時間を溶かしがちです。私が普段実際に使っている診断の順序と、それぞれの修正手順を実例とともに整理しました。読み終えたとき、「次に試すべき手」が必ず 1 つは増えているはずです。

まず把握しておきたい「3 つの兆候」

HMR トラブルは、表に出てくる兆候によって原因の当たりが変わります。次の 3 つのどれに最も近いかを最初に分類してください。

兆候 A: ファイルを保存するとターミナルにビルドログは出るが、ブラウザだけが沈黙している
兆候 B: ファイルを保存してもターミナルに何も出ない（ビルドが走らない）
兆候 C: 起動直後は HMR が効くが、5〜10 分作業すると突然止まる

兆候 A はネットワーク経路の問題、兆候 B はファイルウォッチャーの問題、兆候 C はリソース枯渇の問題であることが明確に多い、というのが個人的な経験則です。以下、それぞれを順に追っていきます。

兆候 A: ブラウザ側だけが反応しない場合

ターミナルに compiled successfully のような出力は出ているのに、ブラウザが更新されないケースです。WebSocket（HMR の通信路）がどこかで遮断されている可能性が高いと考えてください。

最初にブラウザの開発者ツールを開き、Console と Network タブを確認します。WebSocket connection to 'ws://localhost:3000/_next/webpack-hmr' failed のような赤い行が出ていれば、ほぼ確定です。

# Antigravity の統合ターミナルで実行
# Next.js 16 系: HMR の WebSocket ポートを確認
lsof -i -P | grep LISTEN | grep -E "3000|3001|24678"
# 期待される出力例:
# node    12345 ...    TCP *:3000 (LISTEN)

修正の典型パターンは次の 3 つです。第 1 に、Antigravity の組み込みポートフォワーダー（リモート開発時）が WebSocket をプロキシできていない場合があります。コマンドパレットから「Forward a Port」を選び、HMR 専用のポートを明示的に転送してください。第 2 に、ブラウザ拡張機能（広告ブロッカーや CSP 系拡張）が WebSocket を遮断していることがあります。シークレットウィンドウで再現するかを確認するのが最速です。第 3 に、Vite の場合は server.hmr.host や server.hmr.port を環境変数で明示的に指定すると安定します。

// vite.config.ts
import { defineConfig } from 'vite';
 
export default defineConfig({
  server: {
    host: '0.0.0.0',
    port: 5173,
    hmr: {
      // リモートやコンテナ越しでも確実に届けるための明示指定
      host: 'localhost',
      port: 5173,
      protocol: 'ws',
    },
  },
});
// 期待される動作: ブラウザの devtools で
// "[vite] connected." がコンソールに表示される

兆候 B: ファイル保存後、ビルドが走らない場合

ターミナルに何も流れないということは、ファイルウォッチャーが変更を検知していないということです。これが一番厄介で、原因も多岐にわたります。

最初に疑うべきは inotify の上限です。Linux 環境（WSL や Devcontainer 含む）でファイルを監視できる総数には上限があり、大きめのリポジトリでは秒単位で枯渇します。次のコマンドで現状を確認してください。

# 現在の上限
cat /proc/sys/fs/inotify/max_user_watches
# 監視中のファイル数
find /proc/*/fd -lname 'anon_inode:inotify' 2>/dev/null | wc -l
 
# 一時的に増やす
sudo sysctl fs.inotify.max_user_watches=524288
# 永続化する場合
echo "fs.inotify.max_user_watches=524288" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

これに関連した「No space left on device」エラー（実際は inotify 枯渇）の対処は、Antigravity File Watcher の ENOSPC エラー対処法にもまとめてあります。併せてご確認ください。

inotify が原因でなさそうなら、次は監視対象から保存先が除外されていないかを疑います。たとえば Next.js は node_modules、.next、.git を監視対象から外していますが、独自に next.config.js でカスタマイズしている場合や、シンボリックリンク経由でファイルを編集している場合に、編集中のファイルがウォッチャーの管轄外になっていることがあります。

// next.config.js — ウォッチャーを明示的に拡張する例
module.exports = {
  webpack: (config, { dev }) => {
    if (dev) {
      // シンボリックリンク先も含めて監視
      config.watchOptions = {
        followSymlinks: true,
        // 巨大リポでは poll に切り替えると確実だが CPU を食う
        poll: process.env.WATCH_POLL ? 1000 : false,
        ignored: ['**/node_modules/**', '**/.next/**'],
      };
    }
    return config;
  },
};
// 確認方法: WATCH_POLL=1 npm run dev で起動し、
// CPU 使用率が上がりつつもファイル保存で再ビルドが走れば
// ウォッチャー側の問題で確定

兆候 C: 一度は効くが途中で止まる場合

最初は HMR が動いていたのに、数分作業していると突然止まるパターン。原因はほぼ「リソース枯渇」「メモリリーク」「Antigravity 側のセッション切断」の 3 つに絞れます。

メモリの確認は Activity Monitor（macOS）や htop（Linux）で十分です。node プロセスのメモリが 2 GB を超えてきたら要注意で、NODE_OPTIONS=--max-old-space-size=4096 を付けて起動するか、定期的に開発サーバーを再起動する運用に切り替えましょう。

Antigravity 固有の現象としては、AI エージェントが大量のファイル変更を一度にコミットしたあとに、Antigravity 側のインデックスが詰まり、ファイルウォッチャー通知が遅延することがあります。コマンドパレットから「Developer: Restart Extension Host」を実行すると、エディタ全体を再起動せずに復旧できることが多いので、まずこれを試すのがおすすめです。それでも復旧しない場合、ワークスペースのインデックスが壊れているかもしれません。詳しい復旧手順は Antigravity ワークスペースのインデックスが詰まる問題の修正手順にまとめています。

Antigravity 固有のチェックポイント

最後に、Antigravity 特有の設定で見落としがちな項目を 3 つ挙げておきます。

第 1 に、AI エージェント実行中はワークスペースの一部のファイル監視が一時停止する仕様があります。これは大規模な書き換え中の不要な再ビルドを防ぐためのもので、エージェント終了後に自動復帰しますが、終了直後の数秒は HMR が動かないことがあります。「効かない」と感じても、まず数秒待ってもう一度保存してみてください。

第 2 に、設定ファイル .antigravity/settings.json の files.watcherExclude が過剰に広い場合、編集中のファイルが意図せず除外されていることがあります。エディタの「Toggle Developer Tools」から console.log を吐かせて、保存イベントが発火しているかを確認するのが早いです。

第 3 に、Antigravity のリモート開発拡張を使っている場合、ポートフォワーディングの設定が再起動時にリセットされていることがあります。.antigravity/settings.json の remote.autoForwardPorts を true に固定し、HMR 用ポートを remote.portsAttributes に明示しておくと事故が減ります。

全体を振り返って — 次の一歩

HMR の問題は「魔法のようなワンライナーで直る」ものではなく、上記のように 4 領域の切り分けが必要です。今日の作業に戻る前に、まず 1 つだけやってみてほしいことがあります。それは、「自分がいま遭遇している現象が兆候 A・B・C のどれに当たるか」をメモに書き出すことです。これだけで、闇雲に設定をいじって時間を溶かす事態を防げます。

エディタとビルドツールの組み合わせが多様になる時代、ホットリロードの安定性は開発体験そのものを左右します。