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 개발: 완벽한 설정 가이드

Capacitor 작업을 하기에 Linux는 매우 훌륭한 플랫폼입니다. 웹 레이어는 Node 툴링만 있으면 되고, Android 툴링은 네이티브로 실행되며, KVM을 사용하는 Linux 에뮬레이터는 Windows의 동일한 에뮬레이터보다 빠른 경우가 많습니다. 유일한 공백은 iOS입니다. Xcode는 macOS에서만 실행되므로, 이 부분은 클라우드 빌드 서비스가 필요합니다.

이 가이드는 Ubuntu 24.04, Fedora 42, Arch에서 테스트를 마친 전체 Linux 설정 과정을 안내합니다. 마지막에는 Linux에서 다음을 사용하여 iOS를 빌드하는 방법으로 마무리합니다. Capgo 빌드, Mac 없이도 양대 스토어에 모두 배포할 수 있습니다.

Linux에서 가능한 작업과 불가능한 작업

작업	Linux
웹 개발, 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 Simulator	아니요
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 가리키는 JDK를 선택합니다. 잘못된 버전이면 다음과 같은 오류가 나타납니다: 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를 추가하세요:

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 build

Android release build는 완전히 로컬에서 진행됩니다. 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/. 노트북에 서명 키를 보관하고 싶지 않다면, Capgo Android용 Build keystore를 한 번만 저장하면 iOS에서 사용하는 것과 동일한 CLI를 통해 클라우드에서 빌드합니다.

8) Capgo Build를 이용한 Linux에서의 iOS 빌드

Linux만으로는 해결할 수 없는 단계입니다. 워크플로우는 다음과 같습니다:

웹 에셋을 빌드하고 다음으로 동기화합니다: 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 빌드 가이드 모든 클릭 과정을 보여줍니다. 배포 인증서(distribution certificate)를 위해 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을 실행하는 쉘에 export되어 있지 않습니다. 프로필에 추가하고 새 터미널을 열거나, 다음을 생성하세요. 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와 웹 레이어에 대한 전체 Capacitor 루프를 네이티브로 처리하며, 종종 다른 데스크톱보다 더 빠릅니다. iOS의 경우, 로컬에서 프로젝트를 생성하고 에셋을 동기화한 뒤, macOS 작업은 Capgo Build에 맡기세요. 여기에 Live Updates를 결합하면, Apple이 최소 SDK를 변경할 때를 제외하고는 Xcode를 신경 쓸 일이 거의 없습니다.