Can I run the Android emulator inside WSL2?

Technically possible but not recommended. WSL2 has no nested virtualization by default and no GPU passthrough for the emulator. Run the emulator on Windows and connect to it from WSL2 by pointing the WSL adb client at the Windows adb server.

How do I use adb from WSL2 with a phone plugged into Windows?

Either forward the USB device into WSL2 with usbipd-win, or keep adb on Windows and set ADB_SERVER_SOCKET in WSL2 to the Windows host IP on port 5037. The second option is simpler and also works for the emulator.

Where should my Capacitor project live, in WSL2 or on the Windows drive?

Inside the WSL2 file system, for example /home/you/dev. Projects under /mnt/c are several times slower for node_modules and Gradle, and file watchers for live reload often miss changes there.

Can I build iOS from WSL2?

Not locally, since Xcode needs macOS. WSL2 runs the Capacitor CLI and cap sync ios fine, then Capgo Build compiles and signs the ios/ project in the cloud and can submit to TestFlight.

Windows上のWSL2によるCapacitor開発

WSL2はWindows開発者に本物のLinuxシェルを提供します。チームのスクリプトやDockerfile、CIがbashを前提としている場合、これは非常に重要です。Capacitorにおいても、一つのルールを守ることでスムーズに動作します。それは、WebツールチェーンはWSL2に、Androidエミュレータ、USBデバイス、Android StudioはWindows側に置くことです。そして、adbを使って両者をブリッジさせます。

このガイドでは、そのセットアップ方法、多くの人が躓きやすいネットワークの詳細、そしてiOSをどのように組み込むかについて解説します。 Capgo のビルド.

WSL2を導入すべきケース

以下のような場合はWSL2を使用しましょう：

リポジトリにPowerShellでは動作しないbashスクリプト、Makefile、またはHuskyフックが含まれている場合。
ローカル環境とCI環境で同じDockerイメージを実行したい場合。
Linuxの node_modules ファイル構成を採用し、lockfileをLinuxのCI環境と一致させたい場合。

Android Studioとターミナルしか必要ないなら、WSL2は不要です。その場合は、 Windowsネイティブのガイドに従う方がシンプルです。

1) WSL2とディストリビューションのインストール

管理者権限のPowerShellから実行：

wsl --install -d Ubuntu

再起動してUbuntuを開き、Linuxユーザーを作成します。アップデートと基本パッケージのインストールを行います：

sudo apt update && sudo apt install -y build-essential unzip openjdk-21-jdk
curl -fsSL https://bun.sh/install | bash

2) プロジェクトはLinuxのファイルシステム内に保持する

プロジェクトはWindows側ではなく、Linuxのホームディレクトリ配下に作成してください。 /mnt/c:

mkdir -p ~/dev && cd ~/dev
bun create vite@latest my-app
cd my-app
bun install

Windowsのツールからファイルにアクセスするには、 \\wsl$\Ubuntu\home\you\dev\my-app. VS Code でWSL拡張機能を使えば、直接開けます。 code ..

Why this matters: cross-file-system access through /mnt/c 数千もの小さなファイルがある場合、速度が低下します node_modulesまた、Viteが使用するinotify watcherがWindowsドライブ上のファイルに対して正しく動作しません。

3) Android SDK の配置場所を決める

推奨される2つの構成：

構成A (推奨): Windowsに SDK を、WSL2にLinux上の SDK を参照するGradleを配置。 エミュレータとGUIツール用にWindowsにAndroid Studioをインストールし、Gradle用にWSL2内へ別途コマンドライン版 SDK をインストールします：

mkdir -p ~/Android/Sdk/cmdline-tools && cd ~/Android/Sdk/cmdline-tools
# download commandlinetools-linux-*.zip from the Android developer site
unzip commandlinetools-linux-*.zip && mv cmdline-tools latest
echo 'export ANDROID_HOME=$HOME/Android/Sdk' >> ~/.bashrc
echo 'export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools' >> ~/.bashrc
source ~/.bashrc
sdkmanager "platform-tools" "platforms;android-36" "build-tools;36.0.0"
sdkmanager --licenses

はい、数百MBほど複製されます。その代わり、GradleはLinux並みの速度で動作し、Windows側の /mnt/c.

構成B：すべてをWindows上で行い、WSL2はWebビルドのみに使用する。 実行するコマンド： bun run build をWSL2で実行し、 cap sync に加えて gradlew 同じファイル群に対してPowerShellから直接 \\wsl$を実行します。動作はしますが、速度が低下し、2つのシェルが混在することになります。WSL2に何もインストールできない場合にのみ、この方法を選択してください。

本ガイドの以降のセクションでは、構成Aを前提としています。

4) WSL2とWindows間でadbをブリッジする

エミュレーターやUSB接続のデバイスはWindowsに接続されています。WSL2でのGradleビルドや cap run android は、それらにアクセスする必要があります。Windows側で単一のadbサーバーを起動し、WSL2をクライアントとして動作させてください。

Windows側で、すべてのインターフェースで待機するadbサーバーを起動します。WindowsのSDKにあるadbを使用してください：

adb kill-server
adb -a -P 5037 nodaemon server

そのウィンドウは開いたままにしてください。プロンプトが表示された場合は、WSL仮想アダプターに対してWindowsファイアウォールでポート5037を許可してください。

WSL2内のadbクライアントの接続先をWindowsホストに向けます：

export WSL_HOST=$(ip route show default | awk '{print $3}')
export ADB_SERVER_SOCKET=tcp:$WSL_HOST:5037
adb devices

これでエミュレーターや実機がWSL2内で認識されるようになります。2つのadbバイナリのメジャーバージョンが一致している必要があるため、 platform-tools 両方の環境を同時にアップデートしてください。

Mirrored networkingを使うと、これが簡単になります

Windows 11 22H2以降では、mirrored networkingを有効にすることでWSL2がWindowsのネットワークスタックを共有できるようになります。まず、作成または編集して、 %USERPROFILE%\.wslconfig:

[wsl2]
networkingMode=mirrored

実行 wsl --shutdownUbuntuを再起動し、次に ADB_SERVER_SOCKET=tcp:127.0.0.1:5037を使用します。ホストIPが再起動のたびに変わらなくなるため、live reloadもより簡単になります。

代替案：USBデバイスをWSL2にパススルーする

実機を完全にWSL2内のadbで制御したい場合は、usbipd-winを使用します：

winget install usbipd
usbipd list
usbipd bind --busid 2-3
usbipd attach --wsl --busid 2-3

その後、以下のudevルールを追加してください。 Linuxガイド WSL2内での動作です。エミュレータには効果がなく、ネットワーク接続のままです。

5) アプリを実行する

adbブリッジを使用すると、Capacitor はLinuxと同様に動作します：

bun add @capacitor/core @capacitor/android @capacitor/ios
bun add -d @capacitor/cli
bunx cap init
bun run build
bunx cap add android
bunx cap add ios
bunx cap run android

cap open android 同じマシンにAndroid Studioが必要です。代わりに、次のフォルダを android/ WindowsのAndroid Studioで開きます。パスは \\wsl$\Ubuntu\home\you\dev\my-app\androidです。Studio同梱のGradleがWindows上でビルドし、ターミナルはWSL2でビルドします。両者は同じソースファイルを共有します。

6) 境界をまたぐライブリロード

ViteはWSL2で動作し、アプリはWindowsのエミュレータまたは実機で動作します。エミュレータから開発サーバーにアクセスできる必要があります。

すべてのインターフェースにバインドしてViteを起動します：

bun run dev -- --host 0.0.0.0

設定で Capacitor をこのアドレスに向けます： capacitor.config.ts:

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'my-app',
  webDir: 'dist',
  server: {
    url: 'http://10.0.2.2:5173',
    cleartext: true,
  },
};

10.0.2.2 は、ホストマシンに対するエミュレータのエイリアスです。mirrored networkingを使用するとWSL2のポートがWindowsホストから見えるため、このアドレスでViteに到達できます。使用しない場合は、先にWindows側でポートフォワーディングを行ってください：

netsh interface portproxy add v4tov4 listenport=5173 listenaddress=0.0.0.0 connectport=5173 connectaddress=$(wsl hostname -I)

USB接続のデバイスを使用する場合は、URLをWindowsのLAN IPに置き換え、Windowsファイアウォールでポート5173を許可してください。次に、 bunx cap sync android 設定を変更した後に実行し、リリースビルドを行う前に server を削除してください。

7) Capgo Buildを使用したWSL2からのiOSビルド

XcodeにはmacOSが必要ですが、WSL2でネイティブコンパイルまでを行い、残りの工程はCapgoが担当します：

bun run build
bunx cap sync ios
bunx @capgo/cli@latest login
bunx @capgo/cli@latest build init --platform ios
bunx @capgo/cli@latest build request com.example.app --platform ios --build-mode release

CLIが準備された ios/ プロジェクトをアップロードし、ログをWSL2のターミナルにストリーミングします。署名用データはMacなしで、OpenSSLまたは iOS証明書ジェネレーターを使用して作成されます。詳細は CapacitorとCapgo Buildを使用してLinuxからiOSアプリをビルドする方法、これはWSL2でも同様に適用可能です。

8) 日常的な変更にはNative Buildを避ける

両方のアプリがストアにリリースされたら、 Capgo Live Updates GradleやCapgo Native Buildを操作せずに、WSL2からWebの変更をプッシュできます：

bunx @capgo/cli@latest bundle upload --channel production

WSL2でよくある問題

adb: device offline またはWSL2でリストが空になる場合：Windowsのadbサーバーが実行されていない、 -aあるいはバージョンが一致していません。再起動して adb version 両方のバージョンを確認してください。
再起動後にホストIPが変更された：ミラーリングネットワークを使用していない場合は想定内の挙動です。 WSL_HOST exportを ~/.bashrc に記述して再計算させるか、ミラーモードに切り替えてください。
Vite がファイルの変更を検知できない: プロジェクトが以下にあるため /mnt/c。Linux のホームディレクトリへ移動してください。
Gradle が極端に遅い: 原因は同じ、または Gradle キャッシュが /mnt/c。以下に ~/.gradle WSL2 内に保持してください。
時刻のズレにより Apple API 認証が失敗する build init: スリープ後に WSL2 の時刻がズレます。以下を実行して sudo hwclock -s から再試行してください。
cap open android に失敗する: Studio が Windows 上にあります。代わりに Studio からフォルダを開いてください。

まとめ

チームがbash環境をメインとしている場合、WSL2はCapacitorのWebツールチェーンにとって最適な環境になります。エミュレータや実機はWindows側に置き、単一のadbサーバーでブリッジし、ファイルはLinuxのファイルシステムで管理。そしてiOSのコンパイルはCapgo Buildに任せましょう。これにより、WindowsノートPC上でLinuxのワークフローを維持しながら、両方のApp Storeへアプリを配信できます。