본문 바로가기
튜토리얼

Capacitor와 Capgo Build로 Linux에서 iOS 앱 빌드하기

Ubuntu, Fedora 또는 어떤 Linux 환경에서도 서명된 iOS 빌드를 TestFlight에 배포하세요: Capacitor로 ios/ 프로젝트를 생성하고, OpenSSL로 인증서를 만든 뒤, Mac 없이 Capgo Build가 컴파일 및 제출을 처리하도록 하세요.

Capacitor와 Capgo로 Linux에서 iOS 앱 빌드하기 Capgo 블로그 일러스트

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 ios

cap sync 를 복사하고 dist/ 앱으로 보내도록 ios/App/App/public 플러그인 참조를 업데이트합니다. Capgo은(는) 안에 있는 내용을 컴파일하므로 ios/동기화되지 않은 프로젝트는 이전 UI를 배포하게 됩니다.

3) Mac 없이 서명 자료 생성

Apple Distribution 인증서와 .p12, App Store 프로비저닝 프로필, 그리고 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에서는 플래그가 중요합니다. 없으면 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 true

5) 빌드 요청

bun run build
bunx cap sync ios
bunx @capgo/cli@latest build request com.example.app --platform ios --build-mode release

준비된 ios/ 프로젝트가 업로드되고, Capgo이(가) 실행됩니다 pod install, Xcode로 아카이브를 생성하고, 인증서로 서명하며, 로그를 터미널에 스트리밍합니다. 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-upload

CLI은 시간 제한 다운로드 링크를 출력합니다. 다음을 추가하세요 --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 그리고 값을 시크릿으로 전달하세요. 관련 내용은 자격 증명 관리.

8) 네이티브 빌드 없이 일상적인 반복 개발

TestFlight 빌드가 생성된 후에는 대부분의 변경 사항이 웹 변경 사항입니다. 다음을 통해 배포하세요: Capgo Live Update:

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

아껴 두세요 build request 플러그인 추가, 권한 변경, 아이콘 변경 및 Capacitor 업그레이드 시 사용하세요.

Linux 함정

  • 잊지 마세요 cap sync ios: IPA에 구버전 UI가 표시됩니다. 요청 전 반드시 동기화하세요.
  • ios/ 에서 .gitignore: CLI은 디스크에서 업로드하므로 빌드는 되지만, 팀원이나 CI에는 네이티브 프로젝트가 없습니다. 반드시 커밋하세요.
  • .p12 비밀번호 거부됨: 다음으로 재생성 -legacy.
  • Apple 인증 실패: 시계 오차. NTP를 활성화하세요.
  • 플러그인 추가 후 네이티브 리빌드 누락: Capacitor 플러그인을 추가하면 네이티브 바이너리가 변경됩니다. 이를 호출하는 웹 변경 사항을 배포하기 전에 새로운 클라우드 빌드와 스토어 제출을 실행하세요.

요약

Linux에서는 Xcode를 실행할 수 없지만, 그럴 필요도 없습니다. 생성 ios/ Capacitor로 생성하고, OpenSSL로 빌드 인증서를 생성한 후, Capgo Build가 컴파일, 서명 및 TestFlight 전송을 처리하도록 하세요. 웹 레이어의 Live Updates를 사용하면 Linux 전용 팀도 Android만큼 일상적으로 iOS를 배포할 수 있습니다. 전체 환경 설정에 대해서는 다음을 읽어보세요 Linux에서의 Capacitor 개발.

Capacitor 앱용 Live updates

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

블로그 최신 글

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