아래는 “빌드 로그 → 흔한 원인 → 해결 단계” 순서로 정리한 실전 점검 흐름입니다.
먼저, 실패한 로그 라인을 정확히 한 줄로 잡고 거기서부터 역으로 추적하면 시간이 확 줄어듭니다.
아래 키워드가 들어간 로그를 특히 주의해서 보세요: Asset catalog, AppIcon, CFBundleIcons, Info.plist, codesign, entitlements, permission.
대부분은 Xcode 빌드 중간/끝에 이런 형태로 나타납니다.
- error: AppIcon.appiconset 관련: “No image named …”, “Invalid icon name”, “Missing required icon file”
- Asset catalog 관련: “Failed to compile asset catalog”, “actool …”
- Info.plist 관련: “Multiple commands produce … Info.plist”, “The file … Info.plist could not be opened”
- codesign/entitlements 관련: 아이콘 변경 후에도 뜰 수 있는 연쇄 에러(실제 원인은 다른 곳)
팁: Cordova CLI로 빌드했다면 platforms/ios 아래 생성된 Xcode 프로젝트를 열고, 동일한 스킴으로 빌드해서 에러 위치를 더 자세히 보세요.
빌드 로그 패턴 1: Asset Catalog(AppIcon) 컴파일 실패
가장 흔한 흐름은 “아이콘 리소스를 넣었는데 actool이 실패”입니다. 이 경우는 보통 아이콘 세트의 슬롯(필수 크기) 누락, 잘못된 파일 포맷, 또는 프로젝트가 참조하는 AppIcon 세트 이름 불일치로 발생합니다.
- AppIcon 세트 이름: Xcode의 Build Settings에서 Asset Catalog App Icon Set Name이 AppIcon인지, 커스텀 이름인지 확인
- Contents.json: 직접 수정했다면 문법 오류/중복이 없는지 확인
- 파일 포맷: PNG가 아닌 경우(투명/색공간 문제 포함) actool에서 튕길 수 있음
플러그인 충돌 관점에서는, 일부 플러그인이 iOS 리소스/번들 구성을 바꾸거나(rare) 빌드 스크립트를 추가해 asset 처리 타이밍을 건드리면서 문제를 키우는 경우가 있습니다. 최근 추가/업데이트한 플러그인이 있다면 우선 의심 대상에 올려두세요.
빌드 로그 패턴 2: CFBundleIcons/Info.plist 충돌(중복 정의)
아이콘은 보통 Asset Catalog로 관리하는데, 동시에 Info.plist에 CFBundleIcons를 플러그인이나 커스텀 설정이 덮어쓰면 경고/에러로 이어질 수 있습니다. 특히 다음 케이스가 잦습니다.
- config.xml에서 plist 수정을 해둔 상태로 아이콘 방식을 변경
- 어떤 플러그인이 plugin.xml로 Info.plist 항목을 추가하면서 아이콘 관련 키까지 건드림
- 빌드 산출물에 Info.plist가 두 번 생성되거나, 서로 다른 경로의 plist를 참조
해결 포인트는 “한 곳만 진실 소스로 만들기”입니다. iOS에서 AppIcon(Asset Catalog)을 쓸 거면, Info.plist의 아이콘 관련 키를 불필요하게 중복 정의하지 않는 편이 안전합니다.
흔한 원인: 플러그인이 Info.plist/권한 키를 바꾸면서 생기는 연쇄 문제
아이콘 자체가 원인이 아닌데도, 아이콘 작업(리소스 재생성, platform 재추가)을 한 뒤 갑자기 iOS 빌드가 깨지는 경우가 있습니다. 이때는 “아이콘을 바꿨다”가 트리거일 뿐, 실제로는 플러그인 설치 스크립트가 다시 실행되면서 Info.plist/Entitlements가 꼬인 경우가 많습니다.
예를 들면:
- 권한 문구 키(NSPhotoLibraryUsageDescription, NSCameraUsageDescription 등)가 중복/누락되어 워닝이 폭증
- 푸시/로그인 계열 플러그인에서 entitlements나 capabilities에 영향을 줘서 codesign 문제가 함께 발생
- 동일 목적의 플러그인 2개가 plist를 서로 다른 값으로 덮어씀
이 경우는 아이콘 섹션만 붙들면 해결이 안 됩니다. 로그에서 가장 먼저 나온 plist/entitlements 관련 경고부터 같이 정리해야 합니다.
해결 단계(추천 순서): “아이콘 → plist → 플러그인”으로 범위를 좁히기
아래 순서대로 하면 불필요한 시행착오가 줄어듭니다.
- 1) 빌드 산출물 정리: Xcode Derived Data 정리 후 재빌드(오래된 asset 캐시를 먼저 제거)
- 2) AppIcon 세트 확인: platforms/ios의 Assets.xcassets 안에 AppIcon.appiconset이 있고, Xcode에서 누락 슬롯이 없는지 확인
- 3) Info.plist에서 CFBundleIcons 중복 제거: Asset Catalog를 쓰는 경우, 아이콘 관련 키가 불필요하게 들어가 있지 않은지 확인(특히 config.xml/플러그인 주입 흔적)
- 4) 플러그인 영향 범위 확인: 최근 추가/업데이트한 플러그인부터 하나씩 되돌려보며(plist 변경을 유발하는지) 확인
- 5) 재생성 전략: 문제가 꼬였으면 ios platform을 “정리 후 재구성”하는 편이 빠를 때가 많음(단, 커스텀 수정을 했다면 백업 후 진행)
포인트는 “아이콘 파일을 바꿨으니 아이콘만 문제일 것”이라는 가정을 버리는 겁니다. Cordova에서는 아이콘 변경이 리소스 재처리/플러그인 훅 재실행과 엮여서 다른 문제가 같이 드러나곤 합니다.
플러그인 충돌을 빠르게 가려내는 방법(권한/플리스트 중심)
플러그인 충돌 의심 시에는 다음을 확인하면 원인 후보가 빨리 좁혀집니다.
- plugin.xml에서 iOS의 <config-file target="*-Info.plist">를 많이 건드리는 플러그인 찾기
- 동일 권한 키를 여러 플러그인이 추가하는지 확인(예: 카메라/사진 접근, 위치, 블루투스 등)
- 아이콘 변경 직후에만 깨진다면, ios platform 재추가 과정에서 플러그인 설치 순서가 달라졌는지 확인
실무 팁: “아이콘 관련 에러”가 떠도, 로그 초반에 plist 관련 경고가 먼저 쌓이는 경우가 있습니다. 그 경고가 실제 원인인 경우가 있으니, 마지막 에러 줄만 보지 말고 첫 경고부터 읽어보는 습관이 도움이 됩니다.
마무리
iOS 아이콘 이슈는 겉으로는 단순해 보여도, Cordova에서는 Asset Catalog, Info.plist, 플러그인 훅이 한 번에 얽히면서 빌드가 깨지기 쉽습니다. 로그에서 “AppIcon/actool/CFBundleIcons/Info.plist” 중 무엇이 먼저 터졌는지부터 잡고, 그다음에 플러그인 충돌(권한/플리스트 주입)을 점검하는 순서가 가장 안정적입니다.
특정 에러 메시지 한 줄(원문)과 함께 현재 사용 중인 플러그인 목록이 있으면, 어떤 항목이 충돌인지 더 구체적으로 좁혀서 정리할 수 있습니다.