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.

Capacitor Linux 开发：完整配置指南

Linux 是进行 Capacitor 开发的绝佳平台。Web 层只是 Node 工具链，Android 工具链可原生运行，带 KVM 的 Linux 模拟器通常也比 Windows 上的同款模拟器更快。唯一缺口是 iOS：Xcode 只支持 macOS，所以这部分需要云构建服务。

本指南带你完成完整的 Linux 环境配置，已在 Ubuntu 24.04、Fedora 42 和 Arch 上测试。最后会介绍如何在 Linux 上使用 Capgo 构建，无需 Mac 也能上架两个商店。

Linux 上哪些能用，哪些不能用

任务	Linux
Web 开发、Vite、框架工具	是
`cap add android`, `cap sync`，Gradle 构建	是
Android 模拟器	支持，需 KVM
通过 USB 连接的 Android 真机	可以，通过配置 udev rules 实现
Chrome DevTools 远程调试	是
`cap add ios`, `cap sync ios` (生成并复制)	可以，但需注意会跳过 CocoaPods
编译、签名并归档 iOS 应用	不行，需要 macOS。请使用 Capgo Build
iOS 模拟器	否
用于 iOS WebView 的 Safari Web Inspector	否

所有“否”项的操作都将转移到云端或通过 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

你有两个选择。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 添加到你的 shell profile 中：

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

上述 Vendor ID 涵盖了 Google、Samsung 和 OnePlus。如果您的手机不在列表中，请使用 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 上构建 Release 版本

Android release build 完全在本地完成。使用 JDK 的 keytool 生成 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/。如果你不想把签名密钥留在笔记本电脑上， Capgo 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 Build 指南展示每一步点击。对于分发证书，你完全不需要 Keychain Access：生成 CSR 并 .p12 按说明使用 OpenSSL iOS 证书与 provisioning profile 详解，或使用 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

仅在插件变更、权限变更和 Capacitor 升级时才进行 Native Build。

Linux 常见问题

SDK location not found: ANDROID_HOME 未在运行 Gradle 的 shell 中导出。请将其添加到您的 profile 并打开新终端，或者创建 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 daemon 内存不足：添加 org.gradle.jvmargs=-Xmx4g 改为 android/gradle.properties.
Wayland 与 Android Studio 的故障：用以下命令启动 Studio _JAVA_AWT_WM_NONREPARENTING=1 如果窗口一直空白。

总结

Linux 原生支持 Android 和 Web 层的完整 Capacitor 流程，且通常比其他桌面系统更快。对于 iOS，请在本地生成项目并同步资源，然后让 Capgo Build 处理 macOS 部分。配合 Live Updates 使用，你唯一需要想到 Xcode 的时候，就是 Apple 调整最低 SDK 要求时。