본문 바로가기

Capacitor Linux 개발: 완벽한 설정 가이드

Ubuntu, Fedora 또는 Arch에서 Capacitor 워크플로우 전체를 설정하세요: Node 또는 Bun, JDK, Android SDK, KVM이 포함된 에뮬레이터, udev 규칙이 적용된 USB 장치, 그리고 Mac 없이 Capgo Build를 활용한 iOS 빌드.

Capacitor Linux 개발 환경 설정 가이드 Capgo 블로그 일러스트

Linux는 Capacitor 개발에 훌륭한 플랫폼입니다. 웹 레이어는 그저 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 시뮬레이터 아니요
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 도구를 사용할 수 있고, command line tools만으로도 더 가볍게 빌드하기에 충분합니다.

옵션 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: Command line tools만 사용

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

shell profile에 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

위 벤더 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에서 릴리스 빌드

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

8) Capgo Build로 Linux에서 iOS 빌드

이 단계는 Linux만으로는 할 수 없습니다. 워크플로:

  1. 웹 에셋을 빌드하고 다음으로 동기화하세요: ios/.
  2. iOS 서명 자격 증명을 한 번만 저장하세요.
  3. 클라우드 빌드를 요청하세요. 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 빌드 가이드 모든 클릭 과정을 보여줍니다. 배포 인증서의 경우 Keychain Access가 필요하지 않습니다: CSR을 생성하고 .p12 OpenSSL을 사용하여 iOS 인증서 및 provisioning profile 설명에 설명된 대로 처리하거나, iOS 인증서 생성기.

로그가 터미널에 실시간으로 스트리밍됩니다. Linux에서 TestFlight까지의 전체 플로우에 대한 자세한 내용은 Capacitor와 Capgo Build를 사용하여 Linux에서 iOS 앱 빌드하기.

9) Live Updates로 네이티브 재빌드 건너뛰기

네이티브 셸이 스토어에 등록되면, 일상적인 변경 사항은 대부분 JavaScript, HTML, CSS입니다. 이러한 변경 사항은 Linux에서 몇 초 만에 배포할 수 있습니다. Capgo Live Update:

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

네이티브 빌드는 플러그인 변경, 권한 변경, Capacitor 업그레이드 시에만 사용하세요.

Linux 주요 이슈

  • SDK location not found: ANDROID_HOME Gradle을 실행하는 셸에서 내보내지지 않습니다. 프로필에 추가한 후 새 터미널을 열거나, 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의 경우 프로젝트를 로컬에서 생성하고 에셋을 동기화한 뒤, Capgo Build에 macOS 부분을 맡기세요. Live Updates와 함께 사용하면 Apple이 최소 SDK를 변경할 때만 Xcode를 생각하면 됩니다.

Capacitor 앱용 Live updates

웹 레이어 버그가 라이브 상태라면, 앱 스토어 승인을 며칠씩 기다리지 말고 Capgo를 통해 수정 사항을 배포하세요. 네이티브 변경 사항은 정상 리뷰 절차를 그대로 따르는 반면, 사용자는 백그라운드에서 업데이트를 받습니다.

블로그 최신 글

Capgo는 정말 프로페셔널한 모바일 앱을 만드는 데 필요한 최고의 인사이트를 제공합니다.