Cordova iOS 앱이 Xcode에서 갑자기 빌드 실패하거나, 빌드는 되는데 실행 직후 크래시/권한 팝업이 안 뜨는 경우가 있습니다. 이때 원인이 “플러그인끼리의 충돌”이거나 “권한 설정(Info.plist, Entitlements) 누락/불일치”인 경우가 많습니다. 아래 체크리스트는 이 두 축을 빠르게 분리해서 원인 범위를 줄이는 데 초점을 맞췄습니다. 
먼저 ‘한 번에 다 고치려 하지 말고’, 증상을 분류해서 좁혀가면 훨씬 빨라요.
아래 순서는 실제로 시간을 가장 많이 아끼는 흐름(재현 → 분리 → 고정)으로 구성했습니다.
1) 증상부터 분류: 빌드 실패 vs 실행/권한 문제
처음에는 로그가 길어서 막막하지만, 크게는 두 갈래입니다.
- 빌드/아카이브 단계에서 실패: 컴파일 오류, 링크 오류, Pod 설치 문제, 중복 심볼, 헤더 충돌 등(플러그인 충돌 가능성 큼)
- 빌드는 되는데 실행에서 문제: 실행 직후 크래시, 특정 기능에서만 크래시, 권한 팝업 미표시, 카메라/앨범 접근 실패 등(권한/플러그인 설정 이슈 가능성 큼)
가능하면 Xcode의 Report navigator에서 실패 지점을 정확히 잡고, “가장 위의 첫 번째 에러(First error)”부터 보세요. 뒤쪽 에러는 연쇄 반응인 경우가 많습니다.
2) 플러그인 충돌을 빠르게 찾는 방법(최소 변경으로 재현)
플러그인 충돌은 ‘어느 플러그인이 문제인지’만 잡으면 절반은 끝납니다. 시간을 아끼는 핵심은 “플러그인 목록을 한 번에 다 의심하지 않고” 이진 탐색처럼 줄이는 겁니다. 
- 최근 변경 확인: 마지막으로 추가/업데이트한 plugin, Pod, iOS 플랫폼 버전 변경부터 되돌려 재현 여부를 봅니다.
- plugin list 확보: 현재 설치된 플러그인과 버전을 고정(기록)합니다. 같은 오류를 재현/공유할 때 필수입니다.
- 플러그인 비활성화로 좁히기: 의심 플러그인을 하나씩 제거하기보다, 절반씩 빼면서 범위를 줄이면 훨씬 빠릅니다.
- 중복 기능 플러그인 주의: 예) 권한 플러그인 2개, 푸시 플러그인 2개, 카메라/앨범 관련 플러그인 혼재 등은 충돌 확률이 높습니다.
빌드 오류에서 흔한 키워드는 다음이 많이 보입니다: duplicate symbols, linker command failed, framework not found, umbrella header, module map, Swift library 관련 오류. 이런 경우 대체로 플러그인(또는 Pod)이 서로 같은 라이브러리를 다른 방식으로 끌고 들어오거나, iOS 최소 버전/빌드 설정이 어긋난 경우가 많습니다.
3) 권한 체크리스트: Info.plist(Usage Description) 누락/오타
실행은 되는데 카메라/마이크/사진 접근에서 죽거나, 권한 팝업이 안 뜨는 문제는 Info.plist의 Usage Description 누락이 가장 흔합니다. iOS는 특정 권한 접근 시 해당 키가 없으면 크래시로 이어질 수 있어요. 
- NSCameraUsageDescription: 카메라 사용
- NSMicrophoneUsageDescription: 마이크 사용
- NSPhotoLibraryUsageDescription: 사진 라이브러리 읽기
- NSPhotoLibraryAddUsageDescription: 사진 저장/추가
- NSLocationWhenInUseUsageDescription, NSLocationAlwaysAndWhenInUseUsageDescription: 위치 권한
- NSUserTrackingUsageDescription: App Tracking Transparency(추적 허용) 관련
체크 포인트는 “키가 있는가”뿐 아니라, 오타/대소문자, 빌드 타깃에 반영되는 plist가 맞는지입니다. Cordova 설정(config.xml)이 들어가더라도, Xcode 프로젝트에서 실제로 포함되는 Info.plist를 최종 확인하는 습관이 도움이 됩니다.
4) Entitlements/Signing 이슈: Push, iCloud, Keychain 그룹 충돌
권한 팝업과는 성격이 다르지만, Xcode에서 아카이브/서명 단계에서 막히는 문제는 Entitlements 불일치인 경우가 많습니다. 특히 아래 조합에서 자주 터집니다.
- Push Notifications: aps-environment 값이 빌드 구성(Debug/Release)과 맞지 않거나, 프로비저닝과 불일치
- Associated Domains: 도메인 형식 누락/오타, capability 설정 불일치
- Keychain Sharing: keychain-access-groups 값 충돌/중복, 팀 ID 불일치
- Sign In with Apple 등: capability는 켰는데 플러그인/코드가 다른 방식으로 요구
플러그인 하나가 capability를 자동으로 추가하는데, 다른 플러그인이 다른 설정을 기대하면 충돌이 납니다. 이때는 “플러그인 관점의 요구사항”과 “Xcode Signing & Capabilities의 실제 상태”를 맞춰야 합니다.
5) CocoaPods/Framework 정리 포인트: 플러그인끼리 끌어오는 의존성 충돌
Cordova iOS는 플러그인에 따라 CocoaPods 의존성이 붙는 경우가 많고, 여기서 버전 충돌이 나면 Xcode 에러가 폭발합니다. 다음 상황이 대표적입니다.
- 같은 Pod를 다른 버전으로 요구: 어느 한쪽이 업데이트되며 최소 버전이 올라감
- 정적/동적 프레임워크 혼재: 특정 라이브러리가 동적 로딩을 전제로 함
- Swift 관련 설정: Swift 표준 라이브러리 포함/런타임 설정 문제(플러그인 일부만 Swift일 때)
해결은 보통 “Pod 의존성 정리 + 플러그인 버전 고정” 쪽으로 갑니다. 중요한 건, 임시로 빌드만 통과시키는 게 아니라 재현 가능한 상태로 버전을 고정하는 것입니다(팀 작업/CI에서 특히 중요).
6) 최종 점검용: 플러그인/권한 체크리스트(바로 따라하기)
- 최근 변경부터 롤백: 마지막으로 건드린 plugin/플랫폼/iOS 배포 타깃을 되돌려 같은 오류가 사라지는지 확인
- 충돌 의심 플러그인 분리: 기능 중복(권한/푸시/카메라/인앱브라우저 등) 플러그인이 2개 이상이면 우선 정리
- Info.plist Usage Description: 사용하는 권한 키가 모두 존재하는지, 오타/대소문자 오류 없는지 확인
- Entitlements/Signing: 팀/번들/프로비저닝과 capability가 일치하는지, Debug/Release 설정 차이 확인
- Pod 의존성 충돌: 같은 라이브러리를 서로 다른 버전으로 요구하는 플러그인이 있는지 확인 후 버전 고정
- 에러는 ‘첫 번째’부터: Xcode 로그의 연쇄 에러에 휘둘리지 말고 최초 에러를 기준으로 원인을 좁히기
체크리스트를 한 바퀴 돌았는데도 애매하면, “빌드 실패/런타임 실패 중 어디인지”와 “특정 플러그인을 제거하면 사라지는지”만이라도 확정해두면 다음 액션이 훨씬 명확해집니다.
마무리
Cordova iOS 이슈는 겉으로는 Xcode 에러처럼 보여도, 실제로는 플러그인 충돌과 권한/서명 설정 불일치가 원인인 경우가 많습니다. 증상을 먼저 분류하고, 플러그인을 분리하면서 Info.plist와 Entitlements를 같이 점검하면 해결 속도가 확 올라갑니다.
특히 팀 작업이라면 “플러그인 버전 고정 + 변경 이력 기록”만 습관화해도 같은 문제가 반복되는 걸 크게 줄일 수 있어요.