PortalKey Tech BlogPublicationへの投稿
🤖

Capacitor ビルド＆開発環境（WSL & Android編）

da-shibuya
に公開
Android
React
TypeScript
Capacitor
WSL
tech

Capacitorブログシリーズについて

このシリーズでは、Webアプリをモバイルアプリ化するFramework「Capacitor」について、実際の開発で必要になる内容を順に解説していきます。

シリーズ予定：

  1. ✅ Capacitor ビルド＆開発環境（WSL & Android編） ← 今回
  2. Capacitor ビルド＆開発環境（iOS編）
  3. Capacitor FirebaseAppDistributionでアプリ公開
  4. Capacitor WebRTCで通話アプリを作りたかった
  5. Capacitor プッシュ通知実装してみた
  6. Capacitor バックグラウンドでも正しく動くようにしてみた

今回は第1弾として、WSL環境でのAndroidアプリ開発環境構築を解説します。

はじめに

こんにちは！PortalKeyの渋谷です。

WSL上でWeb開発をしていて、「これをモバイルアプリにしたい」と思ったことはありませんか？

今回は、WSL環境で開発したWebサイトをCapacitorを使ってAndroidアプリ化し、実用的な開発・デバッグ環境を構築する方法を紹介します。

この記事でできること：

  • ✅ WSL環境でCapacitor Androidのセットアップ
  • ✅ Android実機・エミュレータでの起動
  • ✅ 実用的なデバッグ環境の構築

開発環境

今回の実装環境は以下の通りです：

前提条件：

  • Webサイトがブラウザで表示できる状態（フレームワーク問わず）

参考（弊社環境）：

  • Vite
  • React
  • TypeScript
  • Electron（Capacitorのアプリ化には無関係）

Capacitorとは

CapacitorはIonic社が開発しているオープンソースのクロスプラットフォームフレームワークです。

WebアプリをそのままiOSやAndroidのネイティブアプリに変換でき、ReactやVueなどのフレームワークに依存しません。

従来のCordovaの後継として開発され、よりモダンなアーキテクチャと優れた開発体験を提供します。

Windows側の準備

Android Studioのインストール

  1. Android Studio公式サイトからインストーラをダウンロード
  2. インストーラを実行し、デフォルト設定でインストール
  3. 初回起動時に「Standard」インストールを選択

Android SDKのセットアップ

Android Studioを起動後：

  1. Settings → Languages & Frameworks → Android SDK を開く
  2. 以下をインストール：
    • Android SDK Platform（最新版推奨）
    • Android SDK Build-Tools
    • Android SDK Platform-Tools
    • Android Emulator（エミュレータを使う場合）

インストール先のパスをメモしておきます（後でWSL側の設定で使用）：

C:\Users\<ユーザー名>\AppData\Local\Android\Sdk

Capacitorの導入

https://capacitorjs.jp/docs/getting-started#既存のウェブアプリケーションにcapacitorを追加する

公式サイトの説明が分かりやすいため詳しくは書きません。
init時に対話形式で決める場所があるため、ご注意ください。
本記事ではWebAssetのディレクトリをdistに設定しています。

WSL側の環境設定

adb.exeへのパス設定

WSLからWindows側のAndroid SDKツールを使えるように、~/.bashrcに以下を追加します：

# Android SDK設定
export ANDROID_HOME=/mnt/c/Users/<ユーザー名>/AppData/Local/Android/Sdk
export ANDROID_SDK_ROOT=$ANDROID_HOME
export PATH=$PATH:$ANDROID_HOME/platform-tools

注意： <ユーザー名>は自分のWindowsユーザー名に置き換えてください。

設定を反映：

source ~/.bashrc

動作確認

Android端末（実機またはエミュレータ）を接続し、以下のコマンドで認識されているか確認：

adb.exe devices

正常に認識されていれば、以下のような出力が表示されます：

List of devices attached
emulator-5554   device

ビルドとインストール

1. Webサイトのビルド

まず、Webサイトをビルドします：

# Viteの場合
npm run build
# または
yarn build

これでdistフォルダ（またはcapacitor.config.tsで指定したディレクトリ）にビルド成果物が生成されます。

2. Capacitorの同期

ビルド成果物をAndroidプロジェクトにコピー：

npx cap sync android

初回およびWebサイトを更新した際は、必ずこのコマンドを実行してください。

3. Androidアプリのビルド

WSL上でAndroidアプリをビルド：

cd android
./gradlew assembleDebug

ビルド成果物は以下に生成されます：

android/app/build/outputs/apk/debug/app-debug.apk

4. 実機へのインストール

adb.exe install -r android/app/build/outputs/apk/debug/app-debug.apk

-rオプションは既存のアプリを上書きインストールします。

複数端末接続時：

# デバイス一覧を確認
adb.exe devices

# 特定のデバイスを指定してインストール
adb.exe -s <device-id> install -r android/app/build/outputs/apk/debug/app-debug.apk

デバッグ環境の構築

実用的な開発には、2つのデバッグ方法を使い分けます。

1. Chrome DevTools（フロントエンドデバッグ）

WebViewのデバッグには、Chrome DevToolsが使えます：

  1. Androidアプリを起動
  2. PCのChromeでchrome://inspect/#devicesを開く
  3. 接続されたデバイス一覧にアプリが表示される
  4. inspectをクリックでDevToolsが開く

これで通常のWeb開発と同じようにコンソールログ、要素検証、ネットワーク監視が可能です。

2. Android Studio Logcat（ネイティブログ確認）

ネイティブ側のログやクラッシュ情報を確認したい場合：

  1. Android Studioを起動
  2. View → Tool Windows → Logcat
  3. デバイスとアプリを選択
  4. ログがリアルタイムで表示される

Capacitorプラグインのログやネイティブエラーはこちらで確認できます。

⚠️ CORSエラー

このまま自身のサーバにアクセスするとCORSエラーが起きることがあります。
AllowedOriginsに
https://localhost
を追加することで解決することが可能です。

後々のiOSのために
capacitor://localhost
も追加しておきましょう。

WSLから直接Runできない問題

cap run androidのようなコマンドは、WSL環境では正常に動作しません。
これはWSLとWindows側のAndroid SDK/Android Studioの統合がうまくいかないためです。

回避策：開発サーバを指定してホットリロード

毎回ビルド・cap sync・インストールするのは非効率です。

そこで、開発サーバを直接指定することで、ホットリロードしながら開発が可能です：

capacitor.config.tsに以下を追加：

const config: CapacitorConfig = {
  appId: 'com.yourapp.app',
  appName: 'YourApp',
  webDir: 'dist',
  // 開発時のみ追加
  server: {
    url: '[開発サーバの画面表示を行っているURLを指定]',
    cleartext: true
  }
};

この設定により、アプリはローカルのdistフォルダではなく、指定したURLからコンテンツを読み込みます。

開発マシンのIPアドレスを指定し、WSLをミラーモードに設定することでアクセスは可能です。

⚠️ WebRTC制約がある場合の注意

WebRTCを使用するアプリでは、セキュリティ上の制約によりlocalhostまたはhttpsが必須です。

そのため、WebRTCを使う場合は例え開発環境であってもhttpsで立ち上げる必要があります。
viteであればvite-plugin-mkcert等のプラグインを用いることで解決が可能です。

エミュレータから開発マシンへのアクセス

https://developer.android.com/studio/run/emulator-networking?hl=ja
http://10.0.2.2を使用することで開発マシンの127.0.0.1にアクセスできるのですが、これはWindowsの127.0.0.1になります。

WindowsからWSLへ直接アクセスさせるにはミラーモードの設定が必要になります。
https://learn.microsoft.com/ja-jp/windows/wsl/networking#mirrored-mode-networking

⚠️Mixed Contentによるエラー

自身の立てたサーバへアクセスを行うとhttpsからhttpへのアクセスとみなされ、Mixed Contentによるエラーが起きると思います。

その場合は
https://capacitorjs.jp/docs/config
の
allowMixedContent
を使用することで動かすことは可能です。

PortalKeyの運用方法

ここまで書きましたが、PortalKeyではホットリロードの対応がまだ済んでいないため、https://localhostをそのまま使用するようにし、アクセスするサーバ側だけをngrokで起動しアクセスするようにしています。

そのため、画面に変更が入るたびにビルドを行っています。
しかし、画面の確認だけであればPCのChromeでも確認が可能なため、そこまで困っていません。

まとめ

WSL環境でもCapacitorを使ったAndroidアプリ開発は十分実用的です。

今回実装したのは：

  • ✅ WSL環境でのCapacitor Androidセットアップ
  • ✅ ビルド・インストールの手順確立
  • ✅ Chrome DevTools + Logcatによるデバッグ環境

runが行えないため高速な開発とまでは行きませんが画面はPCで確認可能なため、開発にそこまで困ってはいません。
ただしWebRTCで通話を作ろうとすると色々地雷があります…がそれは後々語らせていただきます。

次回はiOS編で、macOSでのビルド環境構築を解説予定です！

参考リンク

PortalKey Tech Blog
PortalKey Tech BlogPublication

株式会社PortalKeyの技術ブログです。

Discussion