Capacitor 앱을 개발할 때 Linux는 매우 쾌적한 환경이며, Android 빌드 또한 아무런 제약 없이 가능합니다. 하지만 iOS는 예외입니다. Xcode와 Apple의 서명 도구는 macOS에서만 실행되기 때문입니다. 해결책은 책상 밑에 Mac mini를 두는 것이 아닙니다. 로컬에서 iOS 프로젝트를 생성한 뒤, 클라우드 상의 macOS에서 컴파일하는 것입니다.
이 가이드는 다음 문서의 Linux 버전입니다: Capacitor 및 Capgo Build를 사용하여 Windows에서 iOS 앱 빌드하기. Linux에서 달라지는 부분인 OpenSSL 인증서, Linux shell, Linux runner에서의 CI를 다룹니다.
역할 분담
Capacitor 앱은 두 가지 빌드가 필요합니다:
- 웹 빌드: 사용 중인 프레임워크의 출력물인
dist/을(를) 의미하며, Linux에서 수행됩니다. - Native Build: Xcode 아카이브, 서명, 업로드를 의미하며, 다음 환경에서 수행됩니다: Capgo 빌드 최신 macOS와 Xcode가 설치된 Apple Silicon 머신.
CLI는 준비된 ios/ 프로젝트를 로컬 머신에서 업로드합니다. Git 호스트에 코드를 올릴 필요가 없으며, 의존성 설치가 cap sync 업로드 전 로컬에서 완료되므로 개인 레지스트리 자격 증명이 외부로 유출되지 않습니다.
사전 요구사항
- 로컬에서 빌드 가능한 Capacitor 앱 (모든 프레임워크 지원).
- Linux 환경의 Node 20+ 또는 Bun.
- Apple Developer Program 멤버십.
- OpenSSL (대부분의 배포판에 기본 설치됨).
- Capgo 계정 및 해당 계정에 등록된 앱
bunx @capgo/cli@latest app add.
1) Linux에서 iOS 프로젝트 생성
bun add @capacitor/core @capacitor/ios
bun add -d @capacitor/cli
bunx cap init
bun run build
bunx cap add ios다음과 같은 결과가 나타납니다: Skipping pod install because CocoaPods is not installed. 정상입니다. 해당 ios/ 폴더는 존재해야 하며 커밋해야 합니다. 이 폴더에는 bundle ID, Info.plist, 아이콘 및 네이티브 설정이 포함됩니다.
2) 빌드 전 매번 웹 에셋 동기화
bun run build
bunx cap sync ioscap sync 복사 dist/ 로 ios/App/App/public 및 플러그인 참조를 업데이트합니다. Capgo는 다음 내용을 컴파일합니다: ios/, 따라서 동기화되지 않은 프로젝트는 이전 UI를 배포하게 됩니다.
3) Mac 없이 서명 자료 생성하기
세 가지가 필요합니다: Apple Distribution 인증서, .p12, App Store provisioning profile, 그리고 App Store Connect API 키입니다. Keychain Access는 필요하지 않습니다.
OpenSSL을 사용한 Distribution 인증서
openssl genrsa -out ios_distribution.key 2048
openssl req -new -key ios_distribution.key -out ios_distribution.csr \
-subj "/emailAddress=you@example.com/CN=Your Name/C=US"업로드 ios_distribution.csr Certificates, Identifiers & Profiles에서 Apple Distribution을 선택하고 다운로드하세요. distribution.cer. 변환 및 번들링:
openssl x509 -in distribution.cer -inform DER -out distribution.pem -outform PEM
openssl pkcs12 -export -inkey ios_distribution.key -in distribution.pem \
-out ios_distribution.p12 -legacy이 -legacy OpenSSL 3에서는 flag가 중요합니다. 이 flag가 없으면 Apple 도구에서 거부됩니다. .p12 비밀번호가 맞는데도 잘못된 비밀번호라는 오류가 발생합니다. OpenSSL을 직접 다루고 싶지 않다면, iOS 인증서 생성기 는 브라우저에서도 동일하게 작동합니다.
Provisioning profile 및 API 키
Apple Developer 포털에서 새 인증서를 사용하는 bundle ID용 App Store 프로필을 생성하고 다음을 다운로드하세요: .mobileprovision. App Store Connect에서 App Manager 역할을 가진 API 키를 생성하고 다음을 다운로드하세요: .p8. Key ID와 Issuer ID를 메모해 두세요. iOS 빌드 가이드 에서 각 화면을 확인할 수 있습니다.
Linux에서 프로필을 검사하고 싶으신가요? openssl smime -inform der -verify -noverify -in profile.mobileprovision 는 내장된 plist를 출력합니다.
4) Capgo에 자격 증명 저장
bunx @capgo/cli@latest login
bunx @capgo/cli@latest build credentials save \
--platform ios \
--apple-team-id "TEAMID" \
--apple-key ./AuthKey_KEYID.p8 \
--apple-key-id "KEYID" \
--apple-issuer-id "issuer-uuid" \
--certificate ./ios_distribution.p12 \
--ios-provisioning-profile ./App_Store.mobileprovision또는 실행: bunx @capgo/cli@latest build init --platform ios 가이드 버전을 사용하려면 이 명령어를 실행하세요. Linux에서는 App Store Connect 키 설정 단계가 수동으로 진행되며, 그 외 모든 과정은 프롬프트로 안내됩니다.
만약 Apple에서 인증 오류로 키를 거부한다면, 시스템 시계를 동기화하세요. JWT는 로컬 시간을 기준으로 서명되므로, 시간이 너무 많이 차이 나면 Apple에서 토큰을 거부합니다.
timedatectl status
sudo timedatectl set-ntp true5) 빌드 요청
bun run build
bunx cap sync ios
bunx @capgo/cli@latest build request com.example.app --platform ios --build-mode release준비된 ios/ 프로젝트를 업로드하고, Capgo가 실행되어 pod installXcode로 아카이브하고, 인증서로 서명한 뒤 터미널로 로그를 스트리밍합니다. API 키가 설정되어 있으면 빌드 완료 후 TestFlight로 자동 제출됩니다. iPhone에 TestFlight 앱을 설치하여 실행하세요.
빌드 실패 시 다음을 추가하여 자동으로 진단할 수 있습니다. --ai-analytics; AI 빌드 진단 기능이 Xcode 로그를 읽고 해결 방법을 설명해 줍니다.
6) TestFlight 없이 테스터를 위한 Ad hoc 빌드
UDID로 등록된 QA 기기의 경우, Ad Hoc 프로필을 사용하고 IPA를 아티팩트로 보관하세요:
bunx @capgo/cli@latest build request com.example.app \
--platform ios \
--ios-distribution ad_hoc \
--output-uploadCLI에서 유효 기간이 정해진 다운로드 링크를 출력합니다. 다음을 추가하여 --output-record build.json 링크를 저장하고 테스터를 위한 QR code를 생성하세요.
7) Linux CI 러너를 통한 자동화
동일한 명령어를 모든 Linux CI에서 실행할 수 있습니다. GitHub Actions 예시:
name: iOS build
on:
workflow_dispatch:
jobs:
ios:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: oven-sh/setup-bun@v2
- run: bun install
- run: bun run build
- run: bunx cap sync ios
- run: bunx @capgo/cli@latest build request com.example.app --platform ios --build-mode release
env:
CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}4단계에서 저장한 인증 정보는 Capgo에 보관되므로, 러너에는 토큰만 있으면 됩니다. 또는 CI .env 포함 bunx @capgo/cli@latest build credentials manage 환경 변수를 export하여 secret으로 전달하세요. 자세한 내용은 인증 정보 관리.
8) Native Build 없는 일상적인 반복 작업
TestFlight 빌드가 생성된 후에는 대부분의 변경 사항이 웹 변경 사항입니다. 다음을 통해 푸시하세요: Capgo Live Updates:
bun run build
bunx @capgo/cli@latest bundle upload --channel production예약 build request 플러그인 추가, 권한 변경, 아이콘 변경 및 Capacitor 업그레이드를 위해 필요합니다.
Linux 사용 시 주의사항
- 잊으셨나요?
cap sync ios: IPA에 이전 UI가 표시됩니다. 요청 전 항상 Sync를 진행하세요. ios/에서.gitignore: CLI를 디스크에서 업로드하여 빌드는 되지만, 팀원이나 CI에는 네이티브 프로젝트가 없습니다. 반드시 커밋하세요..p12비밀번호 거부됨: 다음 명령어로 다시 생성하세요-legacy.- Apple 인증 실패: 시간 동기화 오류입니다. NTP를 활성화하세요.
- 플러그인을 추가했지만 네이티브 rebuild를 잊었습니다: Capacitor 플러그인을 추가하면 네이티브 바이너리가 변경됩니다. 해당 플러그인을 호출하는 웹 변경 사항을 배포하기 전에 새로운 클라우드 빌드와 스토어 제출을 진행하세요.
요약
Linux에서는 Xcode를 실행할 수 없지만, 그럴 필요도 없습니다. Generate ios/ with Capacitor, build certificates with OpenSSL, and let Capgo Build compile, sign and send to TestFlight. With Live Updates for the web layer, a Linux-only team ships iOS as routinely as Android. For the full environment setup, read Linux에서 Capacitor 개발하기.
