Capacitor iOS 트러블슈팅: 흔한 오류와 해결 방법

대부분의 Capacitor iOS 문제는 다섯 가지로 나뉩니다: 잘못된 툴체인, 의존성 해결(SPM 또는 CocoaPods), 플러그인에서 발생하는 컴파일 오류, code 서명, 그리고 'plugin is not implemented' 또는 빈 WebView와 같은 런타임 문제입니다. 다음부터 시작하세요 bunx cap doctor, Xcode 26이 선택되어 있는지 확인하고, 다음을 실행하세요 bunx cap sync ios, 그리고 Xcode 빌드 로그의 마지막 오류가 아닌 첫 번째 오류를 읽어보세요.

이 가이드는 Capacitor 8 프로젝트에서 가장 자주 발생하는 오류, 각 오류의 원인, 그리고 해결 방법을 나열합니다. Android의 경우 Capacitor Android 문제 해결 가이드.

빠른 문제 진단 체크리스트

특정 오류를 추적하기 전에 다음을 실행하세요:

bunx cap doctor            # Capacitor, CLI and plugin versions should match
node -v                    # 22 or later for Capacitor 8
xcodebuild -version        # 26.x
xcode-select -p            # should point to the Xcode you expect
bun run build && bunx cap sync ios

• 버전: @capacitor/core, @capacitor/ios 및 @capacitor/cli 메이저 버전이 동일해야 합니다. 불일치는 이상한 컴파일 및 런타임 오류를 유발합니다. 참고 Capacitor 버전 불일치 오류 해결.
• Xcode 하나: Xcode 버전이 여러 개인 경우, xcode-select -p CLI가 어떤 버전을 사용할지 결정합니다. 다음으로 수정하세요 sudo xcode-select -s /Applications/Xcode.app.
• 패키지 매니저: ios/App/CapApp-SPM 이 존재하면 프로젝트는 SPM을 사용합니다. ios/App/Podfile 이 존재하면 CocoaPods를 사용합니다.

툴체인 오류

Xcode 또는 SDK 버전이 너무 낮음

증상: value of type 'WKWebView' has no member 'isInspectable', 안의 Swift 구문 오류 Capacitor, 또는 compiling for iOS 15.0, but module 'X' has a minimum deployment target of iOS 16.0.

Capacitor 8은 Xcode 26이 필요합니다. GitHub Actions에서 macos-latest 항상 최신 Xcode가 포함된 이미지를 가리키지 않습니다. Xcode 26이 포함된 이미지를 고정하고 명시적으로 선택하세요:

- run: sudo xcode-select -s /Applications/Xcode_26.0.app

정확한 경로는 러너 이미지 문서를 확인하세요. 모듈 최소 버전 오류의 경우, 앱의 배포 타겟을 플러그인의 최소 버전으로 올리거나 이전 버전의 플러그인을 사용하세요.

ITMS-90725: SDK version issue 업로드 시

빌드가 Apple이 현재 허용하는 것보다 오래된 SDK로 생성되었습니다. 2026년 4월 28일부터 업로드는 Xcode 26과 iOS 26 SDK로 빌드되어야 합니다. 참고 Capacitor 앱을 위한 Apple의 Xcode 26 요구사항. Capgo 빌드 Mac 러너를 유지 관리하고 싶지 않다면 Xcode 26에서 이미 빌드할 수 있습니다.

Swift Package Manager 오류

Missing package product 'CapApp-SPM'

Xcode가 로컬 패키지를 해결하지 못했거나 캐시가 오래되었습니다.

1. File > Packages > Reset Package Caches.
2. File > Packages > Resolve Package Versions.
3. 앱이 CocoaPods에서 마이그레이션된 경우, CapApp-SPM 프로젝트의 패키지 의존성 탭에 추가되어 App 타깃에 연결되어 있는지 확인하세요.

product 'X' required by package 'capapp-spm' target 'CapApp-SPM' not found

플러그인의 Package.swift 가 Capacitor CLI가 해당 플러그인의 npm 이름으로 생성한 것과 일치하지 않는 패키지 또는 제품 이름을 사용합니다. 이는 플러그인 버그입니다. 플러그인을 업데이트하거나 패치하세요. 플러그인 개발자는 명명 규칙을 여기서 확인할 수 있습니다. Capacitor 플러그인을 SPM으로 마이그레이션.

“설치된 일부 Capacitor 플러그인이 SPM과 호환되지 않습니다”

이 경고가 표시되면 cap sync 최소한 하나의 플러그인에 빠진 항목이 있다는 뜻입니다. Package.swift. 앱에 포함되지 않아 호출 시 “not implemented” 오류가 발생합니다. 플러그인을 업그레이드하거나 SPM을 지원하는 플러그인으로 교체하거나 일단 CocoaPods를 사용하세요.

패키지 식별자 또는 타겟 이름 중복

두 플러그인이 동일한 패키지 ID 또는 타겟 이름(예: Plugin과 같은 일반적인 이름)을 공유합니다. CLI 8.4부터 Capacitor 설정에서 수정할 수 있습니다:

const config: CapacitorConfig = {
  // ...
  experimental: {
    ios: {
      spm: {
        packageOptions: {
          '@acme/capacitor-foo': { symlink: true },
          '@acme/capacitor-bar': { moduleAliases: { Plugin: 'AcmeBarPlugin' } },
        },
      },
    },
  },
};

symlink 고유 경로가 있는 심볼릭 링크 폴더를 통해 CLI가 플러그인을 참조하도록 만듭니다. moduleAliases 해당 의존성의 충돌하는 모듈 이름을 변경합니다. 또한 업스트림에도 충돌을 보고하세요.

수정하지 마세요 CapApp-SPM/Package.swift

CLI는 모든 동기화 시 이를 다시 작성합니다. 로컬 수정 사항은 사라집니다. 대신 experimental.ios.spm 설정 옵션을 사용하세요.

CocoaPods 오류

No such module 'Capacitor'

열었습니다 App.xcodeproj 를 전달하고 App.xcworkspace. 사용하세요 bunx cap open ios. 워크스페이스가 열려 있는데 오류가 계속되면 실행하세요 bunx cap sync ios pods를 재설치하려면.

CocoaPods could not find compatible versions for pod "X"

원인은 두 가지입니다:

1. 오래된 spec repo: 실행 cd ios/App && pod install --repo-update.
2. 버전 고정 충돌: 두 플러그인이 동일한 pod의 호환되지 않는 버전을 요구하는 경우입니다. 에러 메시지에 체인이 출력됩니다. 버전을 엄격히 고정한 플러그인을 업그레이드하거나, 버전을 맞추거나(Firebase의 경우 모든 Firebase 플러그인을 동일한 SDK 버전으로 유지하세요), podspec을 패치하세요.

계속 실패하면 삭제하고 ios/App/Podfile.lock 및 ios/App/Pods다시 sync하세요. 이 과정에서 모든 pod가 업그레이드되므로 그 후 테스트하세요.

The sandbox is not in sync with the Podfile.lock

실행 bunx cap sync ios. 브랜치 전환이나 부분 설치 후에 발생합니다.

Unable to find compatibility version string for object version '70'

여러분의 project.pbxproj 사용 중인 CocoaPods 버전에서 읽을 수 없는 형식을 사용하고 있습니다. CocoaPods를 업데이트(brew upgrade cocoapods 또는 다음에서 버전을 올리세요 Gemfile). 최후의 수단으로, 파일을 백업한 뒤 버전을 낮추세요 objectVersion.

Sandbox: rsync(...) deny(1) file-write-create

Xcode의 User Script Sandboxing이 CocoaPods 프레임워크 임베드 스크립트를 차단합니다. 다음을 활성화하세요: Build Settings > User Script Sandboxing 대상 아니요 App 타겟에서.

could not find module 'Capacitor' for target 'x86_64-apple-ios-simulator'

시뮬레이터 빌드가 Intel용으로 실행 중입니다. Apple Silicon에서는 보통 Xcode가 Rosetta로 실행 중이거나, 예전 EXCLUDED_ARCHS[sdk=iphonesimulator*] = arm64 설정이 예전 우회 방법에서 남은 것입니다. Xcode를 네이티브로 실행하고, App 타겟과 모든 post_install hook에서 해당 설정을 제거한 뒤 clean하고 다시 빌드하세요.

컴파일 에러

Command PhaseScriptExecution failed with a nonzero exit code

이것은 래퍼입니다. Report navigator에서 실패한 build phase를 펼쳐 스크립트 출력을 확인하세요. Capacitor 앱에서 흔한 원인은 다음과 같습니다:

• Run Script에 필요한 node 를 찾지 못하는 경우입니다. Xcode는 셸 프로필을 로드하지 않고 Node가 nvm, fnm 또는 Volta로 설치되어 있기 때문입니다. 스크립트 내에서 node 의 전체 경로를 사용하거나, 스크립트 상단에 PATH 를 export 하세요.
• CI 환경에서 크래시 리포팅 업로드 스크립트(Sentry, Crashlytics)의 인증 정보가 누락되었습니다.
• 사용자 스크립트 샌드박싱(User Script Sandboxing)으로 인해 CocoaPods embed 스크립트가 차단되었습니다(위 내용 참조).

'X' is only available in iOS 16.0 or newer

플러그인이 deployment target보다 높은 API을 사용합니다. Xcode에서, Podfile에서도(platform :ios, '16.0') 타겟을 높이세요(CocoaPods 사용 시). 플러그인 README에서 최소 버전을 확인하세요.

플러그인의 Swift 6 동시성(concurrency) 오류

다음과 같은 메시지가 Sending 'x' risks causing data races 는 플러그인이나 앱 타겟이 Swift 6 언어 모드를 사용할 때 나타납니다. Capacitor 8은 Swift 6을 공식적으로 지원하지 않습니다. 플러그인이 업데이트될 때까지 앱 타겟을 Swift 5 언어 모드로 유지하세요.

Code 서명은

Signing for "App" requires a development team

열기 App target > Signing & Capabilities 그리고 팀을 선택하세요. CI에서는 다음을 전달하세요 DEVELOPMENT_TEAM 대상 xcodebuild 또는 서명 도구를 사용하세요. 에러가 App 대신 pod 리소스 번들을 지목한다면, Podfile에서 번들 타깃의 서명을 비활성화하세요 post_install 훅.

Provisioning profile "X" doesn't include the ... entitlement

프로파일을 재생성하지 않고 기능(Push Notifications, Associated Domains, Sign in with Apple)을 추가한 경우입니다. Apple Developer 포털의 App ID에서 해당 기능을 활성화한 후 프로파일을 새로고침하세요. 저희 iOS 인증서 생성기 Mac 키체인 씨름 없이 인증서를 만들 수 있게 도와주고, UDID 찾기 테스트 기기 등록을 도와줍니다.

Unable to install "App" 기기에서

기기에서 개발자 모드를 켜고(설정 > 개인정보 보호 및 보안 > 개발자 모드) 개발자 인증서를 신뢰한 뒤, 개발 빌드용 프로비저닝 프로필에 기기 UDID가 포함되어 있는지 확인하세요.

런타임 오류

"X" plugin is not implemented on ios

JavaScript 쪽에서 네이티브 구현을 찾지 못했습니다. 다음 순서로 확인하세요:

1. 플러그인이 package.json 그리고 실행한 bunx cap sync ios 설치 후 ...
2. SPM의 경우: 플러그인이 ios/App/CapApp-SPM/Package.swift에 표시됩니다. 그렇지 않다면 없습니다 Package.swift.
3. CocoaPods의 경우: 플러그인이 capacitor_pods Podfile의 블록에 표시되고 pod install 경고 메시지가 출력되지 않았습니다.
4. 동일한 JS 이름을 등록하는 플러그인이 두 개 없는지 확인하세요 (예: 푸시 알림 플러그인 두 개).
5. WKAppBoundDomains 이(가) 포함되어 있지 않습니다 Info.plist, 또는 포함되어 있다면, limitsNavigationsToAppBoundDomains 이(가) 설정되어 있고 localhost 이(가) 목록에 있어야 합니다. 그렇지 않으면 App-bound domains가 플러그인 스크립트 주입을 차단합니다.
6. 빌드 폴더를 정리하고 다시 빌드하세요. 오래된 빌드에는 이전 플러그인 등록 정보가 남아 있습니다.

실행 시 빈 화면(White screen) 발생

먼저 Safari Web Inspector로 WebView를 검사하세요. 대부분의 빈 화면은 JavaScript 에러 때문입니다.

• 잘못된 webDir: capacitor.config.ts 이(가) 다음을 포함하지 않는 폴더를 가리킵니다 index.html. 확인하세요 ios/App/App/public.
• 빌드 타겟 버전이 너무 높음: 번들러가 구형 WebKit이 지원하지 않는 구문으로 출력합니다. Capacitor 8의 최소 iOS 버전은 15이므로 safari15 이상을 Vite/esbuild에서 타겟으로 설정하고 browserslist.
• 절대 경로 에셋: base 번들러 설정에서 CDN 또는 서브패스로 설정하면 로컬 로딩이 깨집니다.
• Live reload에 연결할 수 없음: 개발 서버가 LAN IP(--host 0.0.0.0)에서 리스닝해야 하며, 휴대폰이 동일한 네트워크에 있어야 하고 앱에 로컬 네트워크 권한(설정 > 개인정보 보호 및 보안 > 로컬 네트워크). 릴리스 빌드 전에 설정에서 제거하세요. server.url 릴리스 빌드 전에 설정에서 제거하세요.
• Live update 번들 손상: 앱이 OTA 업데이트를 사용하는 경우, 잘못된 번들이 화면을 백색으로 만들 수 있습니다. Capgo의 업데이트기가 다음 조건에서 자동으로 롤백합니다: notifyAppReady() 적시에 호출되지 않으면. 다음을 참조하세요: updater 문서.

노치 또는 홈 인디케이터 아래 콘텐츠

추가 viewport-fit=cover 뷰포트 메타 태그에 추가하고 패딩을 적용하세요: env(safe-area-inset-top) 및 env(safe-area-inset-bottom). Capacitor 8의 시스템 바 플러그인은 두 플랫폼 모두에서 상태 바 스타일과 가시성을 제어합니다.

키보드가 입력 필드를 가리는 경우

다음 항목 구성 키보드 플러그인 resize 모드 (native, body, ionic 또는 none) 그리고 실제 기기에서 테스트하세요. 시뮬레이터는 키보드 동작 방식이 다릅니다.

App Store Connect 오류

• ITMS-91053: Missing API declaration: 앱 또는 플러그인이 개인정보 보호 매니페스트 항목 없이 필수 사유 API를 사용합니다. 다음을 PrivacyInfo.xcprivacy App 타겟에 사유와 함께 추가하고, 자체 매니페스트를 포함하는 플러그인도 업데이트하세요.
• ITMS-90725: SDK version issue: Xcode 26으로 다시 빌드하세요.
• Invalid Bundle. The bundle ... contains disallowed file 'Frameworks': 프레임워크가 익스텐션이나 다른 프레임워크 내부에 포함되어 있습니다. 다음을 확인하세요. 임베드 앱 익스텐션용 설정.

목록에 없는 오류를 디버깅하는 방법

1. Safari Web Inspector JS 오류 및 네트워크 호출 확인용. 디버그 빌드는 iOS 16.4+에서 검사 가능합니다. 릴리스 빌드의 경우 ios.webContentsDebuggingEnabled: true 일시적으로.
2. Xcode 콘솔 네이티브 로그용, Capacitor의 ⚡️ 각 플러그인 호출을 보여주는 브릿지 메시지 포함.
3. Console.app 기기를 선택한 상태로 크래시 및 시스템 로그를 확인하세요.
4. 격리하기: 새 앱을 생성하고 bun create @capacitor/app, 의심되는 플러그인만 추가하여 에러가 재현되는지 확인합니다.

이 Capacitor 앱 디버깅을 위한 최종 가이드 각 도구에 대해 더 자세히 알아봅니다. 근본 원인이 플러그인 버그라면, patch는 보통 릴리스를 기다리는 동안 가장 빠른 해결책입니다.