WSL2はWindows開発者に本物のLinuxシェルを提供します。チームのスクリプト、Dockerfile、CIがすべてbashを前提としている場合、これは重要です。Capacitorでは、WebツールチェーンをWSL2に、Androidエミュレーター、USBデバイス、Android StudioをWindowsに配置するという1つのルールを守れば、問題なく動作します。その後、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を使用します。WSL 拡張機能付きの VS Code は、Code を直接開きます code ..
なぜこれが重要か: 透過的なファイルシステムアクセスは /mnt/c 内の数千の小さなファイルに対して遅くなります node_modulesまた、Vite が使用する inotify ウォッチャーは、Windows ドライブ上のファイルに対して信頼できず発火しません。
3) Androidの SDK をどこに置くか決める
実用的なレイアウトは2つ:
レイアウト A (推奨): Windows 上に SDK、WSL2 内の Gradle は Linux 上の SDK コピーを指す構成。 エミュレーターと 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並みの速度で動作し、一切触れません /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サーバーを1つだけ置き、WSL2をクライアントとして使います。
Windows側で、全インターフェースで待ち受けるadbサーバーを起動します。Windowsの SDK にあるadbを使ってください:
adb kill-server
adb -a -P 5037 nodaemon server
そのウィンドウは開いたままにしてください。プロンプトが表示されたら、WSL仮想アダプター用にポート5037をWindowsファイアウォールで許可してください。
WSL2では、adbクライアントをWindowsホストに向けます:
export WSL_HOST=$(ip route show default | awk '{print $3}')
export ADB_SERVER_SOCKET=tcp:$WSL_HOST:5037
adb devices
エミュレーターまたはスマートフォンがWSL2内に認識されるようになります。adbバイナリは両方ともメジャーバージョンを揃える必要があるので、 platform-tools 両方を同時に更新してください。
ミラーリングネットワークでこれを簡素化できます
Windows 11 22H2以降では、WSL2がWindowsのネットワークスタックを共有できるようにミラーリングネットワークを有効にします。 %USERPROFILE%\.wslconfig:
[wsl2]
networkingMode=mirrored
実行 wsl --shutdownを作成または編集し、Ubuntuを再起動してから ADB_SERVER_SOCKET=tcp:127.0.0.1:5037を使用します。ホストIPが再起動のたびに変わらなくなり、ライブリロードも簡単になります。
代替案: USBデバイスをWSL2にパススルーする
実機でadbを完全にWSL2内で使用したい場合は、usbipd-winを使用します:
winget install usbipd
usbipd list
usbipd bind --busid 2-3
usbipd attach --wsl --busid 2-3
次に、 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) 日々の変更ではネイティブビルドを避ける
両方のアプリがストアに公開されたら、 Capgo Live Update WSL2からWebの変更をpushして、GradleやCapgo Buildには触れずに:
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. を~/.gradleWSL2 内に保持してください。 - 〜中に時刻のズレで Apple API 認証が失敗する
build init: スリープ後に WSL2 の時刻がズレます。実行してsudo hwclock -s再試行してください。 cap open android失敗します: Studio が Windows 上にあります。代わりに Studio からフォルダを開いてください。
まとめ
チームがbash中心で作業しているなら、Capacitor のWebツールチェーンを動かす場所としてWSL2はうってつけです。エミュレータと実機はWindowsに残し、1つのadb serverでつなぎます。ファイルはLinuxファイルシステムに置き、iOSのコンパイルは Capgo Build に任せましょう。これで、WindowsノートPC上でLinuxワークフローを回しながら、両方のアプリストアに配信できます。