約 4 分で読めます

Android✕WSL2 Webアプリの実機デバッグまでの道 完全版

WSL2でホスティングしているWebアプリをAndroid実機でデバッグしようとすると、地味にハマるポイントが多い。 よく頻繁に沼ったので、陥りそうなところを一気通貫でまとめておく。

TL;DR

  • Webアプリはすべてのネットワークインターフェースでリッスンする
  • ルーターのパケットフィルタリング・Windowsファイアウォール・WSL2のポートプロキシの3段関門を通す必要がある
  • 192.168.x.xでアクセスできても、HTTPS必須の機能（Camera API、Service Workerなど）は動かないので別途対処が必要

全体像

WSL2上のサーバーにAndroid実機からアクセスするには、ざっくり以下を順番に通していく必要があります。

  1. Webアプリをすべてのネットワークインターフェースでリッスンさせる
  2. ルーターのパケットフィルタリングを通す
  3. Windowsファイアウォールで使用ポートを許可する
  4. WSL2 ⇄ ホストマシンのポートプロキシを設定する
  5. Android USBデバッグを設定する
  6. （API利用時）CORS設定を追加する

ひとつずつ見ていきます。

1. Webアプリは0.0.0.0でリッスン

まず開発サーバーがlocalhost以外からの接続を受け付けるようにする必要があります。Viteなら--host 0.0.0.0のように指定して、localhost以外のすべてのネットワークインターフェースからの接続を許可します。

vite --host 0.0.0.0

2. ルーターのパケットフィルタリング

意外と見落としがちなのがルーター側の設定です。Viteの5173や立ち上げたサーバーのポートは、LAN内であってもルーターのパケットフィルタリングで止められることが多いです。

ルーターのパケットフィルタリングやファイアウォールの設定を確認し、該当ポートをLAN内で止めないように設定してください。

3. Windowsファイアウォール

Windows標準のファイアウォールでも、使用するポートに対して許可のルールを設定する必要があります。

（ここに設定画面のスクリーンショットを入れる）

4. WSL2 ⇄ ホストマシンのポートプロキシ

mirroredモードを使用しない（従来のNATモードの）場合、WindowsとWSL2は異なるIPアドレスを持つ別ネットワークとして隔離されています。

そのため「LAN内の外部デバイスからWindowsのIPを介してWSL2内のサーバーへアクセスできるように通信を中継・転送する（ポートフォワーディングする）」という目的で、ポートプロキシが必要になります。

connectaddressに指定するWSL2のIPアドレスは、WSL内でhostname -I（またはip addr）、Windows側からならwsl hostname -Iで確認します。

# ポートプロキシの追加
netsh interface portproxy add v4tov4 listenport=<ポート> listenaddress=* connectport=<ポート> connectaddress=<WSL2のアドレス>

# 確認
netsh interface portproxy show all

# 後片付け（デバッグ後に削除）
netsh interface portproxy delete v4tov4 listenport=<ポート> listenaddress=*

注意: WSL2のIPはシャットダウン・再起動のたびに変わります。固定したい場合は、起動時にプロキシを貼り直すスクリプトが必要です。

（代替）WSL2のmirroredネットワークモードを使う

ポートプロキシを使わない手として、WSL2のmirroredネットワークモードを使う方法もあります。

.wslconfigに以下を書くと、WSL2がホストのIP/ネットワークインターフェースを共有するので、ポートプロキシ自体が不要になります。

.wslconfig
[wsl2]
networkingMode=mirrored

ただしホストとIPを共有することによる問題もあるので注意が必要です。

  • Windows側のサービスとポートが衝突する可能性
  • ファイアウォールやネットワーク周りの挙動が変わる（既存の設定・ツールが想定外の動きをすることがある）

環境によっては逆にハマることもあるので、安定運用ならNAT+ポートプロキシのほうが無難かなと思う。

5. Android USBデバッグ

PCのChrome DevToolsでネットワークなどのデバッグをするには、Android側のデバッグ設定が必要です。これについては別の記事にまとめているのでそちらを参照してください。

kuu-blog.com/android-usb-wireless-debugkuu-blog.com

6. APIのCORS設定

サーバー側でCORSを設定している場合、Originがローカルアドレスになるので、許可するOriginに追加しておきます。

その他のチェックポイント

  • PCとスマホを同じネットワークに繋げる
  • （必要な場合のみ）使用しているPaaSやIDaaSなどのコールバックIP制限にローカルアドレスを追加する

ここまでやれば192.168.xxx.xxx（PCのローカルアドレス）からアクセスできるようになります。

ただし注意点として、HTTPS通信（SSL/TLS）が必要な機能（Camera API、Geolocation、Service Worker、CookieのSecure属性など）が動作しないことがあります。

HTTPSが必要な場合の対処法

http://192.168.x.xではセキュアコンテキスト扱いにならず上記の機能が動かないので、HTTPSが必要なら以下のいずれかで対処します。

mkcertでローカル用の証明書を発行する

mkcertでローカル用の証明書を発行し、開発サーバーをHTTPS化します。Viteなら--httpsオプション + 証明書指定（server.https）で対応できます。

ngrok / Cloudflare Tunnelで外部公開する

ngrokやCloudflare Tunnelで外部公開してHTTPS URLを発行する方法もあります。

この場合はトンネル経由になるので、ポートプロキシやファイアウォール設定すら不要になるケースもあります。ただし通信が外部を経由する点には注意してください。

まとめ

WSL2上のWebアプリをAndroid実機でデバッグするには、0.0.0.0リッスン → ルーター → Windows FW → ポートプロキシ → Androidデバッグ、と複数の関門を順に通していく必要があった。どこか一箇所でも抜けてると繋がらないので、ハマったときは上から順に確認していくのが良さそう。

HTTPS必須の機能を触る場合はmkcertやトンネルでの対処も必要になるので、自分の用途に合わせて選んでみてください。