Saltar al contenido principal

Desarrollo de Capacitor en Windows: Guía de configuración completa

Configura Capacitor en Windows 11: Node o Bun, JDK 21, Android Studio y el emulador, depuración USB, correcciones de PowerShell, problemas de rutas largas y builds de iOS sin Mac con Capgo Build.

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

La mayoría de la documentación de Capacitor da por hecho que usas Mac. Si desarrollas en Windows, la capa web y Android funcionan igual, con algunas trampas específicas de Windows en PowerShell, longitudes de ruta y el emulador. iOS es la única pieza que Windows no puede compilar, y la solución es un build en la nube con macOS.

Esta guía es la configuración completa de Windows 11, desde una máquina limpia hasta un build de Android en un dispositivo y un build de iOS en TestFlight mediante Build de Capgo.

Qué funciona en Windows y qué no

Tarea Windows
Desarrollo web, Vite, herramientas de framework Sí
cap add android, cap sync, builds de Gradle Sí
emulador de Android Sí, con Hyper-V o WHPX
Dispositivo Android físico por USB Sí
Depuración remota con Chrome DevTools Sí
cap add ios, cap sync ios (generar y copiar) Sí, con un aviso de CocoaPods
Compilar, firmar y archivar iOS No, requiere macOS. Usa Capgo Build
Simulador de iOS No
Safari Web Inspector para iOS WebView No

1) Instala Node o Bun

Usa winget desde PowerShell:

winget install OpenJS.NodeJS.LTS
# Or Bun
winget install Oven-sh.Bun

Abre una nueva terminal y confirma:

node --version
bun --version

Corrige la política de ejecución de PowerShell

bunx cap, npx cap y la mayoría de los shims de CLI son .ps1 scripts. Un Windows recién instalado los bloquea con running scripts is disabled on this system. Permite scripts locales una vez:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

2) Instala JDK 21

Capacitor 7 y 8 requieren JDK 21. Android Studio incluye su propio JBR, pero un JDK del sistema evita sorpresas al ejecutar Gradle desde una terminal.

winget install Microsoft.OpenJDK.21

Configurar JAVA_HOME para tu usuario. Desde PowerShell:

[Environment]::SetEnvironmentVariable("JAVA_HOME", "C:\Program Files\Microsoft\jdk-21.0.8.9-hotspot", "User")

Ajusta la carpeta a la versión que instalaste. Después, reinicia la terminal.

3) Instala Android Studio y el SDK

winget install Google.AndroidStudio

Abre Android Studio y deja que el asistente de configuración instale el SDK para C:\Users\<you>\AppData\Local\Android\Sdk. Después, configura las variables de entorno que buscan Gradle y Capacitor:

$sdk = "$env:LOCALAPPDATA\Android\Sdk"
[Environment]::SetEnvironmentVariable("ANDROID_HOME", $sdk, "User")
$path = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$path;$sdk\platform-tools;$sdk\emulator", "User")

Abre el SDK Manager de Android Studio e instala la plataforma que coincida con tu versión de Capacitor: API 36 para Capacitor 8, API 35 para Capacitor 7.

4) Acelera el emulador

El emulador necesita virtualización por hardware. En Windows 11, el emulador usa Windows Hypervisor Platform. Actívalo:

Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform

Reinicia. Si el Device Manager de Android Studio sigue avisando sobre la aceleración, comprueba que la virtualización esté activada en tu BIOS o UEFI y que Core Isolation (Memory Integrity) no la esté bloqueando en CPUs más antiguas.

Crea un dispositivo en el Device Manager, o desde una terminal:

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

5) Depuración USB en Windows

Activa las opciones de desarrollador y la depuración USB en el teléfono. La mayoría de los teléfonos ya no requieren drivers, pero si adb devices sigue vacío, instala el driver USB de Google desde el SDK Manager (pestaña SDK Tools) o el driver del fabricante para dispositivos Samsung.

adb devices

Acepta el prompt de huella digital en el teléfono la primera vez.

6) Ajustes de proyecto para Windows

Tres ajustes que ahorran horas en Windows:

Rutas largas. Gradle y node_modules puede superar el límite de 260 caracteres. Habilita las rutas largas una vez:

git config --global core.longpaths true
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

El segundo comando requiere PowerShell elevado.

Exclusiones de Defender. El escaneo en tiempo real de node_modules, el caché de Gradle y el SDK de Android ralentizan notablemente los builds. Excluye esas carpetas en Windows Security o desde un PowerShell con permisos de administrador:

Add-MpPreference -ExclusionPath "$env:USERPROFILE\.gradle"
Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\Android\Sdk"
Add-MpPreference -ExclusionPath "C:\dev"

Mantén tus proyectos en una ruta corta como C:\dev\my-app, no en Documentos sincronizados con OneDrive.

Finales de línea. de Gradle gradlew el shell script debe mantener los finales de línea LF o el CI de Linux fallará. Añade un .gitattributes:

*.sh text eol=lf
gradlew text eol=lf

7) 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 Windows avisa de que CocoaPods no está disponible. Es normal; la ios/ carpeta se sigue generando y se commitea, y el cloud build se ejecuta pod install después.

Ejecuta en el emulador o en un dispositivo USB:

bunx cap run android

Depura el WebView en Chrome en chrome://inspect.

8) Builds de release de Android

keytool -genkeypair -v -keystore release.jks -keyalg RSA -keysize 2048 -validity 10000 -alias release
cd android
.\gradlew.bat bundleRelease

El AAB está en android\app\build\outputs\bundle\release\. Para un equipo, es mejor guardar el keystore una vez en Capgo y hacer el build en la nube; mira Capgo Build para Android.

9) iOS desde Windows con Capgo Build

Xcode es solo para macOS, por lo que la compilación de iOS ocurre en la infraestructura Mac de Capgo. Desde tu terminal de Windows:

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 recopila tu material de firma. En Windows, la clave API de App Store Connect se crea manualmente en el portal de Apple, siguiendo la guía de build de iOS. El certificado de distribución no requiere Keychain Access: crea el CSR y .p12 con OpenSSL (winget install ShiningLight.OpenSSL.Light) o la versión en el navegador generador de certificados iOS. El paso a paso está en Crea una app iOS desde Windows con Capacitor y Capgo Build.

Cuando el build termina, Capgo puede subirlo a TestFlight para que lo instales en un iPhone real minutos después.

10) Publica cambios web sin recompilar

Con ambas tiendas activas, usa Live Updates de Capgo para cambios en JavaScript, HTML y CSS:

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

Las recompilaciones nativas solo son necesarias para plugins, permisos y actualizaciones de Capacitor.

Problemas comunes en Windows

  • running scripts is disabled on this system: política de ejecución. Ver paso 1.
  • SDK location not found: ANDROID_HOME no configurada para la terminal que ejecuta Gradle. Reinicia la terminal tras configurarla o crea android\local.properties con sdk.dir=C\:\\Users\\you\\AppData\\Local\\Android\\Sdk.
  • Filename too long desde Git o Gradle: habilita las rutas largas, paso 6.
  • El emulador se queda atascado al arrancar: hipervisor no habilitado o virtualización de BIOS desactivada.
  • gradlew: bad interpreter en CI: gradlew se hizo commit con finales CRLF. Corrígelo con el .gitattributes anterior y renormaliza.
  • EPERM o archivos bloqueados durante bun install: Defender o un daemon de Gradle en ejecución bloqueando archivos. Detén el daemon con .\gradlew.bat --stop y añade las exclusiones.

Resumen

Windows cubre Android y la capa web de extremo a extremo. Para iOS, genera el proyecto en local, sincroniza y pasa la ios/ carpeta a Capgo Build. Añade Live Updates y tu equipo de Windows publicará en ambas tiendas sin un solo Mac en la oficina. Si prefieres una shell de Linux en Windows, lee la guía complementaria sobre cómo usar WSL2 para el desarrollo con Capacitor.

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.