Saltar al contenido principal

Desarrollo con Capacitor en Linux: guía completa de configuración

Configura un workflow completo de Capacitor en Ubuntu, Fedora o Arch: Node o Bun, JDK, Android SDK, emulador con KVM, dispositivos USB con reglas udev y builds de iOS sin un Mac usando Capgo Build.

Ilustración del blog: guía de configuración para Capacitor Development on Linux Capgo

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:

  1. Haz el build de tus assets web y sincronízalos en ios/.
  2. Guarda tus credenciales de firma de iOS una sola vez.
  3. 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_HOME no está exportado en la shell que ejecuta Gradle. Añádelo a tu perfil y abre una nueva terminal, o crea android/local.properties con sdk.dir=/home/you/Android/Sdk.
  • Unsupported class file major version: JDK incorrecto. Apunta JAVA_HOME a JDK 21.
  • Pantalla negra o muy lento en el emulador: KVM no está activo. Revisa ls -l /dev/kvm y tu membresía de grupo.
  • adb devices muestra no 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=-Xmx4g a android/gradle.properties.
  • Fallos de Wayland y Android Studio: abre Studio con _JAVA_AWT_WM_NONREPARENTING=1 si 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.

Live updates para apps Capacitor

Cuando un bug de la capa web está en producción, publica el fix a través de Capgo en lugar de esperar días a la aprobación de la app store. Los usuarios reciben la actualización en segundo plano mientras los cambios nativos siguen el flujo de revisión habitual.

Lo último de nuestro blog

Capgo te da la información clave que necesitas para crear una app móvil realmente profesional.