メインコンテンツへスキップ

WindowsでのWSL2を使ったCapacitor開発

WSL2内でCapacitorのWebツールチェーンを動作させ、AndroidエミュレーターとデバイスはWindows側に保持します。adbブリッジング、ミラーリングされたネットワーク、ファイルシステムのパフォーマンス、ライブリロード、そしてCapgo BuildによるiOSビルドに対応。

WindowsのWSL2によるCapacitor開発 Capgo ブログイラスト

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. を ~/.gradle WSL2 内に保持してください。
  • 〜中に時刻のズレで 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ワークフローを回しながら、両方のアプリストアに配信できます。

Capacitor アプリ向けの Live Updates

Web レイヤーのバグが本番で発生したら、App Store の審査を何日も待たずに Capgo で修正を配信しましょう。ネイティブの変更は通常の審査フローに残したまま、ユーザーはバックグラウンドでアップデートを受け取れます。

最新のブログ記事

Capgoは、真にプロフェッショナルなモバイルアプリを作るために必要な最高のインサイトを提供します。