CI/CD를 위한 Capacitor: 일반적인 오류와 해결책

대부분의 Capacitor CI/CD 오류는 동일한 짧은 목록에서 오류가 발생합니다: iOS code 서명, macOS 도구가 누락되거나 outdated, 웹 빌드가 네이티브 프로젝트에 들어가지 못한 경우, 재사용된 빌드 번호, 업로드 시간에 오류가 발생하는 스토어 요구 사항. 각 오류는 알려진 원인과 해결 방법이 있습니다. 이 안내서에서는 pipeline 단계별 오류를 그룹화하고, 오류가 발생하는 이유와 변경해야 할 사항을 설명합니다.

만약에 scratch에서 pipeline을 설정하고 있다면 Capacitor 앱에 대한 CI/CD 설정 먼저 읽고, 이 목록을 사용하여 강화하세요.

단계 1: 웹层 빌드

오류: 네이티브 앱이 오래된 웹 빌드를 배포합니다

증상: CI는 성공했지만 앱은 설치되었지만昨日のUI를 보여준다.

원인: cap sync 그 순간에 있는 것을 복사한다. pipe라인이 웹 빌드 전에 실행되거나, 웹 빌드가 다른 폴더에 쓰면 webDir native 프로젝트는 오래된 파일을 받게된다. cap sync 해결: webDir in capacitor.config.ts폴더가

Fix: 빌더의 출력 폴더와 일치하는지 확인하라. (Vite의 경우

bun install --frozen-lockfile
bun run build
test -f dist/index.html || { echo "web build missing"; exit 1; }
bunx cap sync

Make sure webDir 빌더의 출력 폴더와 일치하는지 확인하라. (Vite의 경우 dist Vite, www Angular와 Ionic을 위한 build 일부 React 환경에 대해

오류: 개발 서버 URL이 설정에 남아있다

증상: 릴리즈 빌드에서는 빈 화면이 나타나거나 로드하려고 시도한다 http://192.168.x.x:5173.

원인: server.url in capacitor.config.ts was set이 설정되어 commit되었다

해결: commit하지 마라 server.url. CI가 설정하지 않는 환경 변수에서 읽어라

import type { CapacitorConfig } from '@capacitor/cli'

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example',
  webDir: 'dist',
  ...(process.env.LIVE_RELOAD_URL && {
    server: { url: process.env.LIVE_RELOAD_URL, cleartext: true },
  }),
}

export default config

오류: 환경 변수가 잘못된 시점에 구축되었다

증상: 생산 앱이 스테이징 API과 통신합니다.

원인: Vite, webpack 및 Angular는 빌드 시간에 인라인 환경 변수를 설정합니다. 실행 시 존재하는 값은 바이너리 내에 존재하며, 동일한 작업으로 빌드된 __CAPGO_KEEP_0__에도 존재합니다. bun run build live update은 동일한 작업으로부터 빌드된 모든 바이너리에서 찾을 수 있는 것이다.

Fix: 장애 요인: lockfile drift cap sync.

CI에서 사용하는 플러그인 버전이 로컬 머신에 설치된 버전과 다르며, 네이티브 컴파일이 미리 정의된 SYMBOL이 없다고 실패하는 경우입니다.

증상: lockfile를 커밋하고

Fix: 설치 시키세요. bun install --frozen-lockfile 또는 npm ci. Pin @capacitor/core, @capacitor/ios, @capacitor/android, 그리고 @capacitor/cli 동일한 버전으로 Capacitor 버전 불일치 오류를 수정하세요.

2단계: 네이티브 도구 체인

장애: 잘못된 Node, JDK, 또는 Xcode 버전

증상: Unsupported class file major version, The engine "node" is incompatible, 또는 Xcode 오류에 대한 SDK 기능.

원인: 호스트드 런너 이미지가 변경되어 Capacitor 8에는 엄격한 최소 버전이 있습니다.

Fix: pipeline에서 모든 버전을 명시적으로 고정하는 대신에 의존하지 않도록 하세요. latest:

- uses: actions/setup-node@v6
  with:
    node-version-file: .nvmrc
- uses: actions/setup-java@v4
  with:
    distribution: temurin
    java-version: '21'
- uses: maxim-lobanov/setup-xcode@v1
  with:
    xcode-version: '26'

Pitfall: Xcode Apple이 더 이상 수용하지 않는 빌드

Symptom: 업로드가 실패하는 메시지로 앱이 SDK으로 빌드되었다고 합니다.

원인: 2026년 4월 28일부터 App Store Connect는 Xcode 26과 iOS 26 SDK이 필요합니다. 자체 호스팅 Mac 및 이전 실행자 이미지는 여전히 Xcode 16으로 기본 설정됩니다.

해결: 선택하십시오 macos-26 Apple의 Xcode 26 __CAPGO_KEEP_0__ 앱 요구 사항 애플의 Xcode 26 요구 사항은 Capacitor 앱에 적용됩니다..

증상:

Symptom: xcodebuild: error: 'App.xcworkspace' does not exist__CAPGO_KEEP_0__ 8 프로젝트는 새로운 Swift Package Manager를 사용하여 빌드합니다.

원인: 새로운 Capacitor 8개의 프로젝트는 Swift Package Manager를 사용하고 빌드합니다. ios/App/App.xcodeproj . 이전 프로젝트는 CocoaPods를 사용하고 빌드합니다. ios/App/App.xcworkspace after pod install . pipeline은 이전 튜토리얼에서 복사한 것으로 workspace를 가정합니다.

Fix: 사용 중인 프로젝트가 어떤 것을 사용하는지 확인하고 올바른 파일을 빌드하세요. 이주를 하는 경우 __CAPGO_KEEP_0__ 앱을 SPM으로 이주하는 방법을 참조하세요. How to migrate your Capacitor app to SPM.

Symptom:

, 또는 플러그인의 Namespace not specified, package attribute is deprecatedafter Android Studio 업데이트 후에 오류가 발생합니다. build.gradle Android Gradle 플러그인을

Fix: pin합니다. android/build.gradle업그레이드 브랜치에서, 플러그인 업데이트를 먼저 진행하십시오. AGP 9에서 Capacitor 플러그인 빌드 오류를 수정하십시오..

스테이지 3: Code 서명

iOS 서명은 Mac에서만 작동합니다.

증상: No signing certificate "iOS Distribution" found, No profiles for 'com.example.app' were found또는 errSecInternalComponent.

원인: Mac의 키체인에 인증서와 Xcode가 프로파일을 다운로드합니다. CI 실행자는 키체인이 잠금된 비인터랙티브 세션에서 있으므로, 인증서를 임시로 잠금 해제된 키체인에导入하고 프로파일을 Xcode 16 이상이 프로파일을 찾는 위치에 설치하십시오.

수정: 사용자 이름

security create-keychain -p "$KEYCHAIN_PASSWORD" ci.keychain
security set-keychain-settings -lut 21600 ci.keychain
security unlock-keychain -p "$KEYCHAIN_PASSWORD" ci.keychain
security import dist.p12 -k ci.keychain -P "$P12_PASSWORD" -T /usr/bin/codesign
security set-key-partition-list -S apple-tool:,apple: -s -k "$KEYCHAIN_PASSWORD" ci.keychain
security list-keychains -d user -s ci.keychain login.keychain

PROFILES="$HOME/Library/Developer/Xcode/UserData/Provisioning Profiles"
mkdir -p "$PROFILES"
cp app.mobileprovision "$PROFILES/"

legacy 대신 Apple DistributionFix __CAPGO_KEEP_0__ plugin build errors with AGP 9 iOS Distribution. fastlane의 setup_ci plus match automates this. Capgo Build takes the certificate and profile as environment variables and does the keychain work on its own machines, so the Linux job never touches security.

__CAPGO_KEEP_0__

Symptom: 오류: 만료된 인증서

증상: 1년 동안 작동하던 pipeline이 밤중에 실패한다.

원인: 애플 배포 인증서와 프로파일은 1년 후 만료된다. Xcode에서 새로운 인증서를 생성하는 팀원도 CI가 사용하는 프로파일을 무효화할 수 있다. bunx @capgo/cli@latest build prescan --platform ios 해결:

팀 캘린더에 만료일자를 기록하고 CI용 공유 배포 인증서를 하나만 유지하고 빌드하기 전에 확인한다.

증상: fastlane이 6자리 code를 기다리며 멈춰 있습니다.

해결책: App Store Connect API 키 (.p8키 ID, 발급자 ID)를 사용하는 대신 Apple ID와 비밀번호를 사용하지 마십시오. 두 단계 인증이 필요하지 않으며 App Manager에만 제한할 수 있습니다. 인증이 여전히 실패하는 경우, 실행자 시계를 확인하십시오: 토큰은 지역 시간으로 서명되었으며 Apple은 시간이 왜곡된 토큰을 거부합니다.

잘못된 점: base64 비밀번호가 디코딩되지 않음

증상: MAC verification failed, invalid keystore format, 또는 base64: invalid input.

원인: base64 값이 복사될 때 줄바꿈이 추가되었거나, 또는 .p12 OpenSSL 3 기본값으로 생성된 base64 값이 macOS에서 읽을 수 없는 경우

해결책: 라인에 한 번에 인코딩하고 사용하세요. -legacy CI/CD pipeline을 만들 때 .p12 OpenSSL 3:

base64 -i dist.p12 | tr -d '\n' > dist.p12.b64
openssl pkcs12 -export -legacy -inkey key.pem -in cert.pem -out dist.p12

Capacitor CI/CD를 위한 일반적인 함정

증상: 업데이트를 서명할 수 없습니다. 왜냐하면 nobody가 키스토어를 가지고 있지 않기 때문입니다.

해결: Play App Signing을 사용하면 키스토어는 업로드 키로 사용되고 Play Console 지원 팀은 새로운 키스토어를 등록할 수 있습니다. CI secret에 키스토어를 저장하고 오프라인 백업을 저장하세요. 한 번에 한 대의 노트북에만 저장하지 마세요. Android 키스토어 생성기 새로운 키스토어를 만듭니다. 시작할 때부터.

CI/CD pipeline 설계

함정: 풀 리퀘스트마다 네이티브 빌드를 실행합니다.

증상: PR 검사 시간이 느리고 macOS 분량 비용이 많습니다.

원인: 호스팅 macOS 빌더에서 iOS 빌드는 대부분의 CI 계획에서 가장 비싼 분량입니다. 대부분의 커밋은 JavaScript만 수정합니다.

해결: PR에 대해 lint, 테스트, 웹 빌드를 실행하세요. 릴리즈 태그 또는 머지에 대해 네이티브 빌드를 실행하세요. PR 프리뷰에 대해 웹 번들을 __CAPGO_KEEP_0__ 채널로 보내고 바이너리 빌드를 생략하세요. 이에 대한 자세한 내용은 mainComparing CI/CD 플랫폼을 사용하여 Capgo 앱을 비교하는 방법 Capacitor 애플리케이션에 대한 CI/CD 플랫폼 비교.

iOS 및 Android 순차적으로 빌드하는 함정

해결: __CAPGO_KEEP_0__ fail-fast: false __CAPGO_KEEP_0__

strategy:
  fail-fast: false
  matrix:
    platform: [ios, android]

Pitfall: 캐싱이 없거나 잘못된 캐싱

Symptom: 매 빌드에서 Gradle 의존성과 CocoaPods 를 다시 다운로드하거나, 스테이징 빌드에서 프로덕션 설정을 스테일 캐시에서 가져옵니다.

Fix: 캐시 ~/.gradle/caches, ~/.gradle/wrapper, 그리고 ios/App/Pods lock파일에 따라 키가 지정된 캐시를 사용하세요. 환경에 따라 캐시를 분할하세요. Capgo 빌드와 함께, 앱당 빌드 캐시를 분할할 수 있습니다. --cache-key prod 그리고 --cache-key staging, 또는 --no-cache clean 빌드를 위해 건너 뛰세요.

통합 프로젝트 경로의 함정

Symptom: could not find capacitor.config 또는 네이티브 프로젝트에서 누락된 플러그인.

Fix: 앱 패키지에서 Capacitor 명령어를 실행하고, __CAPGO_KEEP_1__를 호이스트하여 Capacitor를 실행합니다. node_modulesCapgo CLI는 --path 또한 --node-modules 이것을 위해.

Stage 5: 제출

장애: 재사용된 빌드 번호

증상: “iOS에서는 버전 번호가 이전에 업로드한 버전보다 높아야 합니다. 또는 Google Play에서는 버전 code가 이미 사용된 버전입니다.”

Fix: CI에서 번호를 생성하세요. Fastlane을 사용하여 TestFlight의 최신 빌드를 읽고 1을 더해주세요. Capgo 빌드는 App Store Connect 또는 가장 높은 빌드 번호를 가져옵니다. versionCode Google Play에서 가져와서 증가시킵니다.

위험: 테스트 플라이트에서 빌드가 멈춥니다.

증상: 업로드는 성공하지만 테스터들은 빌드를 절대로 보지 못합니다.

원인: 수출 규제 답변을 빠뜨렸습니다.

해결: 만약에 표준 암호화만 사용한다면 한 번만 선언하세요. ios/App/App/Info.plist 위험: 개인 정보 보호 매니페스트 거부

<key>ITSAppUsesNonExemptEncryption</key>
<false/>

개인정보 보호 매니페스트 거부

증상: 애플에서 보내는 이메일에 대해 필수적인 이유 API 선언이 누락된 경우 (ITMS-91053).

Fix: app 대상에 PrivacyInfo.xcprivacy 를 추가하고 개인 정보 보호 매니페스트 가이드는 Capacitor 앱에 대한 것입니다..

개인 정보 보호 매니페스트 가이드를 참조하세요.

Fix: 오류: 잘못된 아티팩트 유형bundleReleaseGoogle Play는 AAB ( bundleRelease )이 필요합니다. APK가 아닙니다. release 아직도 성공적으로 빌드되며 signingConfigs.release in android/app/build.gradle 에서 먼저 구성하세요. iOS는 개발 또는 ad hoc IPA가 아닌 App Store export가 필요합니다. 빌드 단계에서 export 방법을 확인하세요.

스테이지 6: 실시간 업데이트

장애: 사용자에게 live update를 배포하는 경우 새로운 네이티브 빌드를 필요로 함

증상: 실시간 업데이트 후 앱이 플러그인 메소드를 호출하는 경우에 앱이 충돌하는 경우

원인: 웹 번들에 사용되는 플러그인 버전이 사용자 기기의 앱에 컴파일된 버전보다 새로운 경우

수정: pipeline이 결정하도록 하세요. build needed 0을 반환할 때 네이티브 의존성이 채널에 실시간으로 업데이트된 것과 일치하고, 1을 반환할 때 새로운 바이너리가 필요할 때:

if bunx @capgo/cli@latest build needed com.example.app --channel production; then
  bunx @capgo/cli@latest bundle upload com.example.app --channel production
else
  bunx cap sync
  bunx @capgo/cli@latest build request com.example.app --platform ios
  bunx @capgo/cli@latest build request com.example.app --platform android
fi

또한 파일이 있는 경우 ios/, android/또는 capacitor.config.* 변경될 때 네이티브 경로를 강제로 사용하세요. 전체 패턴은 자동 빌드 live update 또는 네이티브 빌드 선택, 그리고 호환성 규칙은 네이티브 호환성.

가장 많은 함정들을 제거하는 해결책

CI 러너에서 iOS 컴파일 및 서명만 변경하면 됩니다. Keychain 설정, Xcode 업그레이드, macOS 비용, 프로파일 설치가 모두 pipeline에서 사라집니다. Linux 작업이 준비된 프로젝트를 __CAPGO_KEEP_0__ 빌드에 넘겨주면 Capgo 빌드:

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

컨텍스트: Capgo 솔루션 마케팅 페이지. 역할: 짧은 UI 레이블 또는 네비게이션 아이템. 보는 곳: 페이지 솔루션/화이트 레이블.astro. Capgo 제품/브랜드 및 개발자 용어를 정확하게 보존하십시오. 메시지 키 `solutions_white_label_visual_cell3_value` (솔루션 화이트 레이블 시각 셀3 값). Fixing build failures in Capacitor CI/CD pipelines.

__CAPGO_KEEP_0__ CI/CD pipeline에서 빌드 실패를 고치는 방법