Linux es una plataforma excelente para trabajar con Capacitor. La capa web es solo tooling de Node, el tooling de Android corre nativamente y el emulador de Linux con KVM suele ser más rápido que el mismo emulador en Windows. El único hueco es iOS: Xcode solo existe en macOS, así que necesitas un servicio de build en la nube para esa parte.
Esta guía detalla una configuración completa de Linux, probada en Ubuntu 24.04, Fedora 42 y Arch. Termina con un build de iOS desde Linux usando Build de Capgo, para que puedas publicar en ambas tiendas sin tener un Mac.
Qué funciona en Linux y qué no
| Tarea | Linux |
|---|---|
| Desarrollo web, Vite, herramientas de framework | Sí |
cap add android, cap sync, builds de Gradle |
Sí |
| emulador de Android | Sí, con KVM |
| Dispositivo Android físico por USB | Sí, usando reglas udev |
| Depuración remota con Chrome DevTools | Sí |
cap add ios, cap sync ios (generar y copiar) |
Sí, con aviso de que se omite CocoaPods |
| Compilar, firmar y archivar iOS | No, requiere macOS. Usa Capgo Build |
| Simulador de iOS | No |
| Safari Web Inspector para iOS WebView | No |
Todo lo marcado como “No” se mueve a la nube o a un iPhone real con TestFlight. Lo veremos al final.
1) Instala Node o Bun
Capacitor’s CLI requiere Node 20 o superior. Bun funciona como runtime y gestor de paquetes, y es más rápido para las instalaciones.
# 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
Comprueba las versiones:
bun --version
node --version
2) Instalar un JDK
Capacitor 7 y 8 requieren JDK 21. Los paquetes de distribución están bien.
# Ubuntu / Debian
sudo apt install -y openjdk-21-jdk
# Fedora
sudo dnf install -y java-21-openjdk-devel
# Arch
sudo pacman -S jdk21-openjdk
Configurar JAVA_HOME en ~/.bashrc o ~/.zshrc. La ruta depende de la distribución:
# 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
Si tienes más de un JDK instalado, Gradle elige el que JAVA_HOME apunta. Una versión incorrecta aparece como Unsupported class file major version durante cap run android.
3) Instalar el SDK de Android
Tienes dos opciones. Android Studio te ofrece herramientas GUI. Las herramientas de línea de comandos son más ligeras y suficientes para el build.
Opción A: Android Studio
Descarga el tarball de Linux desde el sitio de Android Studio y extráelo:
sudo tar -xzf android-studio-*.tar.gz -C /opt
/opt/android-studio/bin/studio.sh
En el primer inicio, el asistente de configuración instala el SDK en ~/Android/Sdk.
de Capacitor cap open android necesita saber dónde está Studio:
export CAPACITOR_ANDROID_STUDIO_PATH=/opt/android-studio/bin/studio.sh
Opción B: Solo herramientas CLI
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
Añade el SDK a tu perfil de shell:
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
Instala lo que Capacitor necesita y acepta las licencias:
sdkmanager "platform-tools" "platforms;android-36" "build-tools;36.0.0" "emulator"
sdkmanager --licenses
Haz coincidir la versión de la plataforma con la compileSdkVersion en tu generado android/variables.gradle. Capacitor 8 usa 36; Capacitor 7 usa 35.
4) Habilitar KVM para el emulador
Sin KVM el emulador es inutilizable. Comprueba que tu CPU expone la virtualización:
egrep -c '(vmx|svm)' /proc/cpuinfo
Un resultado superior a 0 significa que es compatible. Instala KVM y da acceso a tu usuario:
# 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
Cierra sesión y vuelve a entrar. Crea e inicia un dispositivo:
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
Si el emulador da error de /dev/kvm permisos, el cambio de grupo aún no se ha aplicado. Reinicia.
5) Acceso USB para dispositivos físicos
Linux no permite que los usuarios normales accedan a dispositivos USB por defecto. Añade una regla 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
Los vendor IDs de arriba cubren Google, Samsung y OnePlus. Busca el tuyo con lsusb si tu teléfono no aparece. Activa la depuración USB en el dispositivo, conéctalo, acepta el aviso de la huella digital y luego:
adb devices
6) Crea el proyecto 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 en Linux imprime una advertencia de que CocoaPods no está disponible. Eso es esperado. El ios/ carpeta se crea igualmente y es lo que Capgo Build compila más tarde.
Ejecuta en el emulador o dispositivo:
bunx cap run android
Depura el WebView en Chrome en chrome://inspect.
7) Builds de release en Linux
Las builds de release de Android son totalmente locales. Genera un keystore con el JDK’s keytool:
keytool -genkeypair -v -keystore release.jks -keyalg RSA -keysize 2048 -validity 10000 -alias release
Luego, compila:
cd android
./gradlew bundleRelease
El AAB queda en android/app/build/outputs/bundle/release/. Si prefieres no tener las claves de firma en tu laptop, Capgo Build para Android almacena el keystore una vez y hace el build en la nube con el mismo CLI que usas para iOS.
8) iOS desde Linux con Capgo Build
Este es el paso que Linux no puede hacer por sí solo. El workflow:
- Haz el build de tus assets web y sincronízalos en
ios/. - Guarda tus credenciales de firma de iOS una sola vez.
- Solicita un build en la nube. Capgo compila, firma y puede subir a 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 te guía por las credenciales. En Linux creas manualmente la key API de App Store Connect en el portal de Apple; la guía de build de iOS muestra cada clic. Para el certificado de distribución nunca necesitas Keychain Access: genera el CSR y .p12 con OpenSSL como se describe en Certificados de iOS y perfiles de aprovisionamiento explicados, o usa el generador de certificados iOS.
Los logs se transmiten en vivo a tu terminal. El flujo completo de Linux a TestFlight se detalla en Compila una app de iOS desde Linux con Capacitor y Capgo Build.
9) Evita recompilaciones nativas con Live Updates
Una vez que las shells nativas están en las tiendas, la mayoría de los cambios diarios son de JavaScript, HTML y CSS. Esos se pueden desplegar desde Linux en segundos con Live Updates de Capgo:
bunx @capgo/cli@latest init
bun run build
bunx @capgo/cli@latest bundle upload --channel production
Reserva las compilaciones nativas para cambios en plugins, permisos y actualizaciones de Capacitor.
Problemas comunes en Linux
SDK location not found:ANDROID_HOMEno está exportado en la shell que ejecuta Gradle. Añádelo a tu perfil y abre una nueva terminal, o creaandroid/local.propertiesconsdk.dir=/home/you/Android/Sdk.Unsupported class file major version: JDK incorrecto. ApuntaJAVA_HOMEa JDK 21.- Pantalla negra o muy lento en el emulador: KVM no está activo. Revisa
ls -l /dev/kvmy tu membresía de grupo. adb devicesmuestrano permissions: regla udev ausente o no recargada. Desconecta y vuelve a conectar tras recargarla.- El demonio de Gradle se queda sin memoria: añadir
org.gradle.jvmargs=-Xmx4gaandroid/gradle.properties. - Fallos de Wayland y Android Studio: abre Studio con
_JAVA_AWT_WM_NONREPARENTING=1si las ventanas siguen en blanco.
Resumen
Linux gestiona todo el ciclo de Capacitor para Android y la capa web de forma nativa, y a menudo más rápido que otros escritorios. Para iOS, genera el proyecto en local, sincroniza tus assets y deja que Capgo Build se encargue de la parte de macOS. Combínalo con Live Updates y solo pensarás en Xcode cuando Apple cambie su SDK mínimo.