Can I develop Capacitor apps on Linux?

Yes. Linux is a first-class environment for the web layer and for Android. You install Node or Bun, a JDK, the Android SDK and optionally Android Studio. The only thing Linux cannot do locally is compile and sign the iOS app, because Xcode only runs on macOS. Capgo Build handles iOS builds in the cloud from a Linux machine.

Do I need Android Studio on Linux to build a Capacitor app?

No. The Android command line tools (sdkmanager, platform-tools, build-tools) plus a JDK are enough to run cap sync, Gradle builds and the emulator. Android Studio is useful for the visual debugger, profiler and emulator manager, but it is optional.

Can I build an iOS app from Linux?

You cannot run Xcode on Linux, so you cannot compile or sign iOS locally. You can generate the ios/ project with Capacitor, sync your web assets into it, and send it to Capgo Build, which compiles and signs it on macOS hardware and can submit it to TestFlight.

Why does the Android emulator run slowly on Linux?

The emulator needs hardware acceleration through KVM. Check that virtualization is enabled in your BIOS, install the KVM packages, and add your user to the kvm group. Without KVM the emulator falls back to software rendering and is unusable.

LinuxでのCapacitor開発：完全セットアップガイド

LinuxはCapacitorの作業に最適なプラットフォームです。WebレイヤーはNodeツールだけで、Androidツールはネイティブに動作し、KVMを使ったLinuxのエミュレータはWindows上の同じエミュレータより高速なことがよくあります。唯一のギャップはiOSです。XcodeはmacOSにしかないため、その部分にはクラウドビルドサービスが必要です。

このガイドでは、Ubuntu 24.04、Fedora 42、Archで検証済みの完全なLinuxセットアップを順に解説します。最後に、LinuxからiOSビルドを行う方法を扱います。 Capgo のビルドMacを持っていなくても、両方のストアへリリースできます。

Linuxでできること、できないこと

タスク	Linux
Web開発、Vite、フレームワークのツール群	はい
`cap add android`, `cap sync`, Gradleビルド	はい
Androidエミュレータ	はい、KVMを使用すれば可能です
USB接続による実機のAndroidデバイス	はい、udevルールを使用すれば可能です
Chrome DevTools によるリモートデバッグ	はい
`cap add ios`, `cap sync ios` (生成してコピー)	はい、ただしCocoaPodsがスキップされる点にご注意ください
iOS のコンパイル、署名、アーカイブ	いいえ、macOS が必要です。Capgo Build を使用してください
iOS シミュレーター	いいえ
iOS WebView 用 Safari Web Inspector	いいえ

「No」の行にある項目はすべて、クラウドまたはTestFlightを使用した実機のiPhoneへ移行します。詳細は最後に説明します。

1) Node または Bun をインストール

CapacitorのCLIにはNode 20以降が必要です.Bunはランタイムおよびパッケージマネージャーとして動作し、インストールも高速です。

# Bun (recommended)
curl -fsSL https://bun.sh/install | bash

# Or Node via your package manager
# Ubuntu / Debian
sudo apt install -y nodejs npm
# Fedora
sudo dnf install -y nodejs
# Arch
sudo pacman -S nodejs npm

バージョンを確認：

bun --version
node --version

2) JDKをインストールする

Capacitor 7および8にはJDK 21が必要です。ディストリビューションのパッケージで問題ありません。

# Ubuntu / Debian
sudo apt install -y openjdk-21-jdk

# Fedora
sudo dnf install -y java-21-openjdk-devel

# Arch
sudo pacman -S jdk21-openjdk

設定 JAVA_HOME における ~/.bashrc または ~/.zshrc. パスはディストリビューションによって異なります：

# Ubuntu / Debian
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
# Fedora
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk
# Arch
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk

複数のJDKがインストールされている場合、Gradleは設定された JAVA_HOME パスを参照します。バージョンが間違っている場合は、 Unsupported class file major version 中に cap run android.

3) Android SDK のインストール

2つの方法があります。Android StudioならGUIツールが使えます。コマンドラインツールだけでもより軽量で、ビルドには十分です。

方法A: Android Studio

Android StudioのサイトからLinux用のtarballをダウンロードして展開します：

sudo tar -xzf android-studio-*.tar.gz -C /opt
/opt/android-studio/bin/studio.sh

初回起動時にセットアップウィザードが SDK を ~/Android/Sdk.

Capacitor の cap open android Studioのインストール先を指定する必要があります：

export CAPACITOR_ANDROID_STUDIO_PATH=/opt/android-studio/bin/studio.sh

方法B: コマンドラインツールのみ

mkdir -p ~/Android/Sdk/cmdline-tools
cd ~/Android/Sdk/cmdline-tools
# Download "Command line tools only" for Linux from the Android developer site, then:
unzip commandlinetools-linux-*.zip
mv cmdline-tools latest

シェルプロファイルに SDK を追加します：

export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools
export PATH=$PATH:$ANDROID_HOME/emulator

Capacitor に必要なものをインストールし、ライセンスに同意します：

sdkmanager "platform-tools" "platforms;android-36" "build-tools;36.0.0" "emulator"
sdkmanager --licenses

プラットフォームのバージョンを compileSdkVersion 生成された android/variables.gradle. Capacitor 8 は 36 を使用、Capacitor 7 は 35 を使用。

4) エミュレータ用の KVM を有効にする

KVM がないとエミュレータは使えません。CPU が仮想化をサポートしているか確認してください：

egrep -c '(vmx|svm)' /proc/cpuinfo

結果が 0 より大きければサポートされています。KVM をインストールし、ユーザーにアクセス権を付与してください：

# Ubuntu / Debian
sudo apt install -y qemu-kvm
# Fedora
sudo dnf install -y qemu-kvm
# Arch
sudo pacman -S qemu-base

sudo usermod -aG kvm $USER

ログアウトして再ログインします。デバイスを作成して起動します：

sdkmanager "system-images;android-36;google_apis;x86_64"
avdmanager create avd -n pixel8 -k "system-images;android-36;google_apis;x86_64" -d pixel_8
emulator -avd pixel8

エミュレータが権限についてエラーを出す場合は、 /dev/kvm グループの変更がまだ反映されていません。再起動してください。

5) 実機の USB アクセス

Linux ではデフォルトで一般ユーザーが USB デバイスにアクセスできません。udev ルールを追加してください：

sudo tee /etc/udev/rules.d/51-android.rules > /dev/null <<'EOF'
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", MODE="0666", GROUP="plugdev"
SUBSYSTEM=="usb", ATTR{idVendor}=="04e8", MODE="0666", GROUP="plugdev"
SUBSYSTEM=="usb", ATTR{idVendor}=="2a70", MODE="0666", GROUP="plugdev"
EOF
sudo udevadm control --reload-rules
sudo usermod -aG plugdev $USER

上記のベンダー ID は Google、Samsung、OnePlus をカバーしています。お使いの端末の ID は次で確認してください： lsusb 端末が一覧にない場合は、USB デバッグを有効にして接続し、フィンガープリントのプロンプトを承認してから、次を実行してください：

adb devices

6) Capacitor プロジェクトを作成する

bun create vite@latest my-app
cd my-app
bun install
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

cap add ios Linux上ではCocoaPodsが利用不可であるという警告が表示されますが、これは想定内の動作です。 ios/ フォルダ自体は作成され、後にCapgo Buildがコンパイルに使用します。

エミュレーターまたは実機で実行:

bunx cap run android

ChromeでWebViewをデバッグ: chrome://inspect.

7) Linuxでのリリースビルド

Androidのリリースビルドは完全にローカルで行えます。JDKを使用してkeystoreを生成し、 keytool:

keytool -genkeypair -v -keystore release.jks -keyalg RSA -keysize 2048 -validity 10000 -alias release

次にビルドを実行:

cd android
./gradlew bundleRelease

AABファイルは以下に出力されます: android/app/build/outputs/bundle/release/. ノートPCに署名鍵を保存したくない場合は、 Capgo Build (Android) keystoreを一度保存するだけで、iOSと同じCLIを使用してクラウド上でビルドできます。

8) Capgo Buildを使用したLinuxからのiOSビルド

これはLinuxだけではできないステップです。ワークフローは次のとおり：

Webアセットをビルドし、以下に同期： ios/.
iOSの署名認証情報を一度保存するだけです。
クラウドビルドをリクエストします。Capgo がコンパイルと署名を行い、TestFlightへアップロードできます。

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

build init 認証情報について順を追って案内します。Linuxでは、Appleポータルで App Store Connect の API キーを手動で作成します。その iOSビルドガイドクリック操作をすべて示します。配布用証明書に Keychain Access は一切不要です。CSRを生成し、 .p12 OpenSSLで、次の説明に従って iOS証明書とプロビジョニングプロファイルの解説、または次を使用： iOS証明書ジェネレーター.

ログはターミナルにリアルタイムで流れます。LinuxからTestFlightまでの全フローの詳細は Capacitor と Capgo Build を使って Linux から iOS アプリをビルドする.

9) Live Updates で Native Build をスキップする

ネイティブシェルがストアに公開された後は、日常的な変更のほとんどは JavaScript、HTML、CSS です。これらは次を使用して Linux から数秒で配信できます： Capgo Live Updates:

bunx @capgo/cli@latest init
bun run build
bunx @capgo/cli@latest bundle upload --channel production

Native Build は、プラグインの変更、権限の変更、および Capacitor のアップグレード用に取っておきましょう。

Linux でよくある問題

SDK location not found: ANDROID_HOME が Gradle を実行するシェルでエクスポートされていません。プロファイルに追加して新しいターミナルを開くか、作成してください android/local.properties を使用して sdk.dir=/home/you/Android/Sdk.
Unsupported class file major version: JDK が正しくありません。 JAVA_HOME JDK 21 に設定してください。
エミュレーターの画面が真っ暗、または非常に遅い: KVM が有効になっていません。 ls -l /dev/kvm およびグループのメンバーシップ。
adb devices 表示 no permissions：udevルールが見つからないか、リロードされていません。リロード後にデバイスを抜き差ししてください。
Gradleデーモンがメモリ不足になる：追加 org.gradle.jvmargs=-Xmx4g まで android/gradle.properties.
WaylandとAndroid Studioの不具合：Studioを次のコマンドで起動 _JAVA_AWT_WM_NONREPARENTING=1 ウィンドウが空白のままの場合。

まとめ

LinuxはAndroidとWebレイヤーのCapacitorループをネイティブで処理でき、他のデスクトップ環境より速いことも多いです。iOSはローカルでプロジェクトを生成してアセットを同期し、macOS側の処理はCapgo Buildに任せましょう。これにLive Updatesを組み合わせれば、Xcodeを意識するのはAppleがSDKの最小要件を変更したときだけになります。