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

전통적으로 iOS 앱을 빌드하려면 Xcode가 필요하고, Xcode가 필요하다는 건 macOS가 필요하다는 뜻입니다. 팀 전체가 Windows나 Linux를 쓰거나 Mac 빌드 머신을 유지하고 싶지 않다면 이 제약은 꽤 번거롭습니다.

다음 조합: Capacitor (native iOS 프로젝트 생성용) 및 Capgo 빌드 (클라우드에서 컴파일 및 서명 수행) Windows 워크스테이션에서 iOS 빌드와 TestFlight 제출을 할 수 있습니다.

이 가이드에서는 팀에서 잘 통하는 실용적인 워크플로우를 소개합니다:

일반적인 웹 프로젝트처럼 Windows에서 개발하세요.
유지하세요 ios/ 레포지토리에 (네이티브 상태를 재현할 수 있도록).
실행 cap sync 로컬에서 (웹 빌드 결과물을 iOS 프로젝트로 복사할 수 있도록).
Capgo Build로 iOS 클라우드 빌드를 실행하세요.

실제로 무엇을 어디서 빌드하나

Capacitor 앱에는 두 가지 별도의 “빌드”가 있습니다:

웹 빌드 (JS/HTML/CSS): Windows에서 로컬로 처리합니다.
Native Build (Xcode 아카이브, 서명, 업로드): Capgo Build가 클라우드의 Mac 하드웨어에서 처리합니다.

이 분리가 핵심입니다: Capgo Build는 네이티브 프로젝트를 컴파일하지만, 웹 에셋이 이미 동기화되어 있다고 가정합니다 ios/.

사전 요구사항

동작하는 Capacitor 앱 (프레임워크는 아무거나 됩니다).
Apple Developer 계정.
업로드할 앱의 App Store Connect 접근 권한 (TestFlight/App Store 제출용).
Capgo 계정과 API 토큰 (CAPGO_TOKEN).

1) Capacitor 앱 생성 또는 준비 (Windows)

이미 웹 앱이 있다면 Capacitor 단계로 건너뛰세요.

Vite 사용 예시:

bun create vite@latest my-app
cd my-app
bun install

Build는 정적 에셋을 생성해야 합니다 (Vite에서는 dist/ 기본값입니다):

bun run build

2) Capacitor 및 iOS 플랫폼 추가

Capacitor 설치:

bun add @capacitor/core @capacitor/ios
bun add -d @capacitor/cli

iOS 플랫폼 폴더 초기화 및 생성:

bunx cap init
bunx cap add ios

이제 다음과 같은 ios/ 디렉토리가 생성됩니다. 이를 git에 커밋하세요. Capgo Build는 내부에 있는 파일을 컴파일합니다. ios/따라서 버전 관리되고 재현 가능해야 합니다.

3) 빌드 전 항상 웹 에셋을 iOS로 Sync 하세요

웹 앱을 변경할 때마다 Windows에서 다음 과정을 수행하세요:

bun run build
bunx cap sync ios

cap sync 빌드된 웹 에셋을 네이티브 iOS 프로젝트로 복사합니다 (Capgo Build가 실제로 컴파일할 파일들).

4) Capgo CLI 설치 및 인증

Capgo Build는 Capgo CLI를 통해 트리거됩니다. bun를 사용하려면 bunx:

bunx @capgo/cli@latest login

또는 shell/CI 환경 변수로 토큰을 설정하세요:

export CAPGO_TOKEN="your_api_key_here"

5) 클라우드 빌드용 iOS Signing 구성

iOS를 빌드하려면 Signing 자료가 필요합니다:

Apple Distribution 인증서 (".p12) 및 비밀번호
프로비저닝 프로파일 (.mobileprovision)
App Store Connect API 키 (AuthKey_XXXXXX.p8) 및 메타데이터 (Key ID, Issuer ID, Team ID)

이 파일들을 아직 생성해야 한다면, Capgo 문서를 참고하세요:

자격 증명 관리 (저장 항목 및 방법)
iOS 인증서 및 프로비저닝 프로필 가져오기

가장 쉬운 방법은 다음과 같습니다: 한 번만 생성/내보내기(보통 사용 가능한 Mac, 팀원, 또는 일시적 대여를 사용)한 후, 이후 모든 빌드에서 Windows에서 재사용하는 것입니다.

파일을 로컬에 확보했다면, Capgo Build를 위해 저장하세요:

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --certificate ./cert.p12 \
  --p12-password "password" \
  --provisioning-profile ./profile.mobileprovision \
  --apple-key ./AuthKey.p8 \
  --apple-key-id "KEY123" \
  --apple-issuer-id "issuer-uuid" \
  --apple-team-id "team-id"

팁: CI에서는 자격 증명 파일을 base64 인코딩하여 시크릿으로 저장하고, 런타임에 디코딩한 뒤 동일한 명령을 실행하세요 build credentials save 명령어만 실행하면 됩니다.

6) Windows에서 iOS Build 실행하기

앱 폴더에서:

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

터미널에서 실시간 로그를 확인할 수 있습니다. App Store Connect 키가 설정되어 있다면, Capgo Build가 생성된 빌드를 TestFlight에 자동으로 제출합니다.

7) 빠르게 반복하기: 웹 변경 사항은 Live Updates로

Capgo Build는 네이티브 변경 사항에 사용됩니다:

Capacitor 플러그인 추가/제거
네이티브 권한 변경
아이콘/스플래시 변경
Capacitor 업데이트
Swift/Objective-C 코드 변경

일상적인 UI 수정과 JavaScript 수정에는 보통 Live Update (OTA)를 사용하므로 매번 네이티브 바이너리를 다시 빌드할 필요가 없습니다.

권장하는 팀 워크플로우는 다음과 같습니다:

빈번한 웹 변경 사항에는 Live Updates를 사용하세요.
네이티브 변경이 필요할 때 가끔 Capgo Build를 사용하세요.

Windows에서 흔히 겪는 문제 (및 해결 방법)

잊기 쉬운 사항 cap sync: iOS 빌드에 UI 변경 사항이 반영되지 않았다면, 웹 앱은 빌드했지만 동기화하지 않았을 가능성이 큽니다. ios/.
커밋하지 않음 ios/: Capgo Build는 네이티브 프로젝트를 컴파일합니다. 폴더가 git에 없거나 빌드 컨텍스트에 포함되지 않으면, 빌드는 앱을 재현할 수 없습니다.
네이티브 재빌드 없이 플러그인 변경: 플러그인 추가는 네이티브 변경입니다. 이후 Capgo Build 실행(및 스토어 제출)을 계획하세요.

요약

Windows에서는 Xcode를 실행할 수 없지만, 다음과 같이 Windows에서 iOS 앱을 출시할 수 있습니다:

Capacitor로 웹 앱을 래핑하세요 (ios/ 레포지토리에서).
웹 에셋을 로컬에서 빌드한 다음, cap sync.
Capgo Build를 사용해 CLI에서 iOS 바이너리를 컴파일하고 서명한 뒤 제출하세요.

Capacitor와 Capgo Build로 Windows에서 iOS App 빌드하기 이어가기

사용 중이라면 Windows에서 Capacitor와 Capgo Build로 iOS 앱 빌드하기 CI/CD 자동화를 계획하려면, 다음을 연결하세요 Capgo CI/CD 설정하기 Capgo CI/CD의 제품 워크플로우용, Capgo Native Build Capgo Native Builds의 제품 워크플로우용, Capgo 연동 서비스 Capgo Integrations의 제품 워크플로우용, CI/CD 통합 CI/CD Integration의 구현 세부 사항은, 그리고 GitHub Actions 연동 GitHub Actions Integration의 구현 세부 사항을 참고하세요.