Hot Reloadがトンネル越しで壊れる理由とその解決策

Viteや Next.js は、ファイル保存時にブラウザタブをリフレッシュしません。変更されたモジュールを持続的な WebSocket 接続を通じてプッシュし、実行中のページにパッチを適用します。高速ですが、これがローカル開発サーバーをクライアントやスマホ、Webhook プロバイダーと共有する際に脆弱になる理由でもあります。

ほとんどの汎用トンネルは、HTTPリクエストは問題なく処理しますが、HMR（Hot Module Replacement）が依存する WebSocket のアップグレードハンドシェイクを適切に処理できません。この部分では、その原因、トンネルが実際に必要とする違い、そして現在利用されている2つのツール — 1つはオープンソース、もう1つはより広範な AIエージェント開発ツールに組み込まれているもの — について解説します。

なぜ WebSocket の問題が特に失敗の原因となるのか

WebSocket は、Upgrade: websocket と Connection: Upgrade ヘッダーを持つ普通の HTTP リクエストとして始まります。サーバー（またはそれを代理するもの）は、そのハンドシェイクを認識し、接続をリクエスト/レスポンスから生の長時間持続可能な双方向バイトストリームに切り替える必要があります。これを明示的に考慮しないトンネルは、これらのヘッダーを削除したり、長時間ハングしているリクエストのように見えてタイムアウトさせたりすることがあります。

この問題は具体的に2つの場所で現れます:

Vite. リバースプロキシ（またはトンネル）が WebSocket トラフィックを正しくプロキシしない場合、Vite のクライアントは HMR ソケットを 直接 開発サーバーに接続し、プロキシをバイパスします — これによりコンソールに警告が表示されます。Vite のドキュメントでは、このフォールバックエラーは通常のローカルネットワークでは無視できると記載されています。直接接続は成功するためです。ただし、公開トンネル経由では「直接」接続は外部から到達できないため、フォールバックも失敗し、HMRが壊れます。解決策としては、WebSocket トラフィックを通すようリバースプロキシを設定するか、server.ws（clientPort、port）を設定してクライアントとサーバーがソケットの到達方法を合意できるようにします。

Next.js. バージョン12以降、Next.jsは /_next/webpack-hmr で WebSocket を使った Fast Refresh を行い、旧来のサーバー送信イベント（SSE）方式から切り替えています。ブラウザと開発サーバーの間に誤設定されたプロキシがあると、「WebSocketが確立前に閉じられた」エラーが頻繁に報告されます。これを防ぐには、開発サーバーの前にあるものが WebSocket のアップグレードをそのまま通すように設定する必要があります。

これらは特定のトンネルベンダーに固有の問題ではなく、ViteやNext.jsのHMRの実装方法に起因します。中間に位置するツールはこれらを積極的に処理しなければなりません。

“フレームワーク認識”トンネルが正しく動作させるために必要なこと

• アップグレードハンドシェイクを認識し、接続を生のTCPパススルーに切り替える。
• 定期的なping/pongフレームで接続を維持し、アイドル状態の長時間接続をファイアウォールやロードバランサーに切断させない。
• Host/Origin ヘッダーを改ざんしない。開発サーバーはセキュリティ上、これらのチェックを行うため、誤った書き換えはリクエスト拒否の原因となる。

今日実際にこれを行っている2つのツール

OutRay — オープンソース、セルフホスト対応

OutRayは、実在し積極的にメンテナンスされているオープンソースプロジェクト（AGPL-3.0、執筆時点でGitHubスター約1,000）で、ngrokの代替として位置付けられています。HTTP、TCP、UDPトンネルをCLIからサポート（outray http 3000、outray tcp 5432）、カスタムドメイン、トラフィック分析ダッシュボード、フレームワーク連携もあります。

Express連携は公式にnpmミドルウェアパッケージ（@outray/express）としてドキュメント化されており、インポートしてアプリにラップすると、通常のサーバーログとともにトンネルURLを出力します。Next.js、Vite、NestJS用のプラグインもリストされていますが、特にnext.config.tsを自動編集するという具体的な主張は未確認です（自己検証推奨）。確かな点は、オープンソースであり、トラフィックを第三者に預けずに全スタックを検査・セルフホストできることです。

AgentsRoom — より大きなツールにバンドルされたトンネル（スタンドアロンではない）

最初の草稿ではこれを「ブラウザネイティブなlocalhost共有ツール」と表現していましたが、誤解を招くため修正します。AgentsRoomは、複数のAIコーディングエージェント（Claude Code、Codex、Antigravity CLIなど）を管理するネイティブデスクトップアプリ（Mac/Linux/Windows）です。タスクボード、プロジェクトごとのターミナル、アプリ内ブラウザ自動化QAエージェント、iOS/Androidのサイドカーアプリを備えています。localhostトンネルはその一機能であり、単体の製品ではありません。ブラウザ内で動作するわけではなく、デスクトップダッシュボードやモバイルアプリから起動します。

AgentsRoomのドキュメントによると、トンネル機能は開いているローカルポートをスキャンし、カスタムサブドメインを選択可能、HTTP/WebSocketトラフィックをNext.js、Vite、Expo Metroなどの開発サーバーにプロキシします。起動は2秒未満を謳い、25秒のハートビートと最大5回の自動再接続を行い、停止時にはスタイリッシュなオフラインページを表示します。モバイルアプリからリモートでトンネルを開始でき、スマホからサイトをプレビュー可能です。

注意点として、これは単なるトンネルではなく、単一の独立開発者（App Storeの記載より）によるもので、無料プランは3プロジェクトまでに制限されています。完全に無料ではなく、利用範囲に注意が必要です。

ngrokの立ち位置と比較

ngrokに対する帯域制限や「一時的URL」の批判は妥当です。ngrokの料金プランでは、無料版は1GB/月のデータ転送と20,000リクエスト/月に制限され、3つのエンドポイントと1つの自動割当ドメインがあります。無料HTTPエンドポイントにはインタースティシャルページ（バイパス可能なヘッダーもあり）もあります。

ただし、「ngrokの無料プランはセッションタイムアウトを厳格にしていない」という点は誤りです。ngrokのドキュメントには、無料エンドポイントはタイムアウトなく長時間動作可能と明記されています。2時間のセッションタイムアウトの噂は誤りです。ソースはngrokの公式ドキュメント。

実用的なポイント

ViteやNext.jsを使っていてWebSocketのフォールバック警告が出た場合、まずは設定を見直すのが良いです。server.wsの設定や、プロキシがUpgradeヘッダーを通すようにするなどです。公開HTTPS URLが必要な場合は、WebSocketアップグレードに対応したトンネルを使うと設定が楽になります。選択肢の中では、OutRayのようなオープンソース・セルフホスト対応のツールと、AgentsRoomのような大規模ツールにバンドルされたトンネルの違いを理解しておくと良いでしょう。信頼性やメンテナンスの観点も重要です。

---

チェンジログ

2026年7月28日に一次資料と照合しながら改稿・事実確認済み。

1. SEO対策の削除：キーワードフレーズを削除し、実際の技術的内容に焦点を当てて再構成。
2. AgentsRoomの説明修正：ブラウザネイティブのツールではなく、ネイティブデスクトップアプリでAIコーディングエージェントを管理するツールであることを明示。
3. OutRayの主張緩和：next.config.tsを自動編集するという具体的な主張は未確認とし、npmの公式ページの情報を引用。
4. ViteのWebSocketフォールバックの説明修正：エラーは通常無視できることを追記し、 tunnel経由では接続できない場合にのみ問題となることを明示。
5. Next.jsのHMR詳細確認：v12以降、/_next/webpack-hmrでWebSocketを使ったFast Refreshに切り替わったことを記載。
6. ngrokの制限と誤解の訂正：公式ドキュメントの数値を引用し、「2時間のセッションタイムアウト」誤情報を訂正。
7. トーンの調整：宣伝色を排除し、純粋な技術解説に徹した内容に修正。