Cordova 프로젝트에서 아이콘을 Android/iOS로 분기하다 보면, iOS 쪽에서만 갑자기 “AppIcon이 비어있다”거나 “필수 아이콘이 없다”는 메시지가 나오며 Archive가 막히는 경우가 있습니다. 대개는 아이콘 파일 자체가 문제가 아니라, config.xml의 icon 선언과 resources(또는 cordova-res) 생성 결과, 그리고 Xcode의 Asset Catalog 연결이 어긋난 상태입니다.
아래 순서대로 보면 원인을 빠르게 좁힐 수 있습니다.
1) 어떤 에러/경고인지 먼저 분류하기(메시지별 출발점)
iOS 아이콘 이슈는 메시지가 비슷해도 원인이 조금씩 다릅니다. Xcode 빌드/Archive 로그에서 아래 유형 중 어디에 가까운지 먼저 잡아두면, 뒤에서 확인할 파일이 줄어듭니다.
- AppIcon 관련: “AppIcon is missing”, “AppIcon is empty”, “Missing required icon file”
- Asset Catalog 관련: “Asset catalog compile failed”, “actool error”
- Info.plist 관련: “CFBundleIconName”, “CFBundleIcons” 언급
이번 글은 특히 Android/iOS 분기 과정에서 iOS의 AppIcon 연결이 끊긴 케이스에 초점을 둡니다.
2) Android/iOS 분기 방식부터 확인(한 프로젝트에서 섞일 때 흔한 함정)
아이콘을 “플랫폼별로 다르게” 운영하려다 보면, 다음 중 하나를 선택하게 됩니다.
- 단일 config.xml + 플랫폼별 icon 선언 (권장: 관리 포인트가 한 곳)
- 빌드 스크립트로 config.xml을 교체 (주의: 교체 타이밍에 따라 iOS 플랫폼이 오래된 설정을 들고 있을 수 있음)
- resources 폴더를 환경별로 교체 (주의: iOS는 결국 Xcode Asset Catalog로 컴파일되므로 “복사만”으로 끝나지 않음)
iOS에서 AppIcon 누락이 뜨는 경우는 보통 “분기 자체”가 문제가 아니라, 분기 후 iOS 플랫폼에 반영되는 단계(prepare/생성)가 빠졌거나 어딘가에서 이전 결과물이 남아 충돌하는 경우가 많습니다.
3) config.xml의 icon 선언 점검(플랫폼 지정과 경로가 핵심)
Cordova는 icon을 여러 방식으로 해석합니다. iOS만 문제라면, 먼저 platform name="ios" 아래 선언이 있는지, 그리고 경로가 실제 존재하는지 확인합니다.
- <platform name="ios"> 아래에 iOS용 icon이 정의되어 있는가
- icon의 src 경로가 현재 브랜치/환경에서 실제로 존재하는가(대소문자 포함)
- Android용 아이콘이 iOS에 “공통”으로 먹도록 작성해둔 경우, iOS에서 기대하는 규격/구조와 충돌하지 않는가
특히 macOS 파일시스템/깃 설정에 따라, 로컬에서는 되는데 CI나 다른 머신에서 깨지는 경우가 있습니다. iOS는 대소문자나 경로 오타에 더 자주 발목이 잡힙니다.
또 하나: iOS는 최종적으로 Xcode의 Asset Catalog(보통 AppIcon.appiconset)을 컴파일하므로, config.xml에 icon을 적어도 플랫폼 준비 과정에서 asset이 제대로 생성/갱신되어야 합니다.
4) iOS Asset Catalog(AppIcon) 생성/연결 상태 확인(Xcode에서 보는 포인트)
빌드 로그에서 AppIcon이 없다고 하면, Xcode 프로젝트에서 다음을 확인합니다.
- Xcode에서 Images.xcassets 안에 AppIcon 세트가 존재하는가
- AppIcon 세트가 있어도 비어있거나 일부 슬롯만 채워진 상태가 아닌가
- Target 설정에서 App Icons Source가 올바른 AppIcon을 가리키는가
- iPad 지원/마케팅 아이콘(1024) 등 필수 슬롯이 요구되는 설정인지
Android는 리소스 폴더에 png가 들어가면 “그럴듯하게” 넘어가는 경우가 많지만, iOS는 Asset Catalog 단계에서 요구되는 조합이 채워져야 통과합니다. 따라서 “파일은 있는데 AppIcon이 비었다”는 느낌의 이슈는 대체로 여기에서 잡힙니다.
5) cordova-res / resources 산출물 점검(생성 도구와 결과물이 불일치할 때)
최근에는 아이콘/스플래시 생성에 cordova-res를 쓰는 경우가 많습니다. 분기 작업을 했다면 다음을 체크합니다.
- 현재 브랜치/환경에서 cordova-res 실행 결과가 iOS까지 제대로 생성되는가
- 생성된 iOS 산출물이 platforms/ios 쪽에 반영되었는가(prepare 과정 포함)
- 기존에 수동으로 손댄 AppIcon이 남아 있어, 생성 결과와 충돌/덮어쓰기가 반복되지 않는가
실무에서는 “Android 아이콘만 바꿨다”는 커밋이 iOS에도 영향을 주는 경우가 있습니다. 이유는 단순합니다. resources나 config.xml이 공용이고, iOS가 원하는 형식(Asset Catalog)이 맞춰지지 않으면 iOS만 실패합니다.
6) 플러그인/권한 체크리스트(아이콘 이슈처럼 보이지만 빌드가 엉키는 원인 정리)
아이콘 경고가 “첫 번째로 눈에 띄는 증상”이고, 실제로는 프로젝트 상태가 꼬여 있는 경우도 있습니다. 아래는 iOS 빌드를 안정화하는 데 도움이 되는 최소 체크리스트입니다.
- 플랫폼 상태: iOS 플랫폼을 오래 유지했다면, 분기 적용 전후로 prepare가 누락되지 않았는지 확인
- plugin.xml 훅: 특정 플러그인이 iOS 프로젝트 파일(Xcodeproj/Info.plist)을 수정하면서 Asset Catalog 설정을 건드리지는 않는지
- 권한 문자열: Info.plist에 권한 키가 추가되면서 빌드 설정이 바뀐 시점과 아이콘 이슈가 같은 커밋인지(상관관계 확인)
- 빌드 캐시: Derived Data나 이전 산출물이 남아, AppIcon 세트가 갱신되지 않은 것처럼 보이지 않는지
핵심은 “아이콘만” 보지 말고, iOS 빌드 파이프라인(prepare → Xcode asset compile → archive) 중 어디서 꼬였는지 단계별로 보는 것입니다.
마무리
iOS의 “AppIcon 누락/비어있음”은 아이콘 파일이 없어서라기보다, 분기 적용 이후 iOS Asset Catalog가 기대하는 형태로 갱신되지 않은 상태에서 자주 발생합니다. config.xml의 iOS 선언, resources/cordova-res 산출물, Xcode의 AppIcon 연결을 순서대로 보면 대부분 정리됩니다.
한 번 해결한 뒤에는 “분기 스크립트가 실행되는 타이밍”과 “prepare/생성 단계”를 고정해두면 같은 문제가 재발할 확률이 크게 줄어듭니다.