링크 단계에서 XCFramework 아키텍처 오류가 나거나, 로컬은 성공하는데 원격 Mac CI만 실패합니다. 빠른 해결: XCFramework에 목표 플랫폼 변형이 있는지 먼저 확인하고, 그 변형의 아키텍처와 실제 링크 파일, 빌드 환경을 차례로 대조하십시오. Rosetta 실행이나 바이너리 무작정 병합은 첫 조치로 삼지 마십시오.
이 글은 XCFramework를 빌드해 배포하는 SDK 및 이진 의존성 유지 담당자를 위한 점검 절차입니다. 원격 Mac CI에서 Xcode 27 Beta 빌드가 실패하는 CI 엔지니어와 Apple 플랫폼 개발자도 대상입니다.
첫 단계: 실패가 컴파일, 링크, 실행 중 어디서 났는지 분리합니다
오류 문구만 보고 Xcode 27 Beta 문제로 단정하지 마십시오. 먼저 실패한 타깃, 빌드 목적지, 전체 오류 로그, 사용한 의존성 버전을 같은 기록에 남깁니다. 컴파일 오류인지, 링커가 필요한 심볼이나 아키텍처를 찾지 못한 것인지, 빌드 뒤 실행 단계에서 실패한 것인지 구별해야 합니다.
같은 커밋과 같은 빌드 목적지로 본인 Mac과 원격 Mac CI를 비교하십시오. 성공과 실패가 갈리는 위치가 확인되면 의존성 패키지, 빌드 설정, 원격 환경 중 조사할 범위를 좁힐 수 있습니다. Apple의 Xcode 릴리스 노트 목록에는 여러 버전의 릴리스 노트가 함께 제공됩니다. 작업 환경에서 실제로 선택된 Xcode 버전과 일치하는 문서를 확인하십시오.
작업 시점에 확인된 Xcode 27 Beta 6 릴리스 노트는 베타 버전의 변경 정보를 담고 있습니다. 이를 정식 안정 버전의 동작으로 일반화하지 마십시오. 베타의 특정 오류인지 판별하려면 로그와 실제 도구 체인을 함께 보관하고, 해결 여부는 프로젝트가 쓰는 빌드 목적지로 재현해야 합니다.
둘째 단계: 목표 플랫폼 변형이 패키지에 있는지 확인합니다
XCFramework는 여러 Apple 플랫폼을 위한 framework 또는 library 변형을 묶는 형식입니다. 따라서 CPU 이름이 같다는 사실만으로 iOS 기기용, iOS Simulator용, macOS용, Mac Catalyst용 바이너리를 서로 바꿔 쓸 수 있다고 판단해서는 안 됩니다. Apple의 다중 플랫폼 바이너리 번들 안내에 따라 각 변형의 플랫폼 및 목적지를 확인하십시오.
패키지 안의 Info.plist를 열어 AvailableLibraries 항목을 살펴봅니다. SupportedPlatform은 플랫폼을, SupportedPlatformVariant는 필요한 경우 시뮬레이터와 같은 변형을 식별하는 데 쓰입니다. 현재 빌드 목적지와 일치하는 항목이 없다면 아키텍처를 추가하는 것만으로 해결되지 않습니다. 공급자에게 해당 목적지의 변형을 요청하거나, 소스가 있다면 필요한 플랫폼을 포함해 다시 빌드해야 합니다.
명령줄에서는 다음처럼 선언된 항목을 확인할 수 있습니다.
plutil -p path/to/Library.xcframework/Info.plist목적지가 iOS Simulator인데 패키지에 iOS 기기 변형만 있다면, 기기 바이너리에 시뮬레이터 아키텍처를 덧붙이는 방식은 올바른 플랫폼 변형을 만들어 주지 않습니다. 먼저 패키지에 Simulator용 항목이 있는지 확인하십시오.
셋째 단계: 선택된 변형에 필요한 아키텍처가 있는지 대조합니다
목표 플랫폼 변형이 존재한다면, 다음은 그 안에 실제로 어떤 아키텍처가 포함되어 있는지 확인할 차례입니다. Info.plist의 SupportedArchitectures 선언을 읽고, 해당 LibraryPath가 가리키는 framework 또는 library 바이너리도 직접 검사하십시오.
lipo -archs path/to/Selected.framework/Selected명령 출력이 빌드 로그의 목적지와 맞지 않는다면, 대상 변형에 필요한 슬라이스가 빠졌을 가능성이 있습니다. 특히 Apple Silicon Simulator에서 의존성이 링크되지 않을 때는 시뮬레이터용 변형과 그 바이너리의 아키텍처를 따로 확인하십시오. Apple의 TN3117 아키텍처 빌드 오류 안내도 오류 진단에 참고할 수 있습니다.
주의: Xcode를 Rosetta로 실행해 문제가 사라졌다고 해서 의존성 패키지가 올바른 것은 아닙니다. 빌드 목적지에 맞는 변형과 슬라이스가 실제로 있는지 검증한 뒤, 필요한 경우 의존성을 업데이트하거나 다시 빌드하십시오.
넷째 단계: 패키지 선언과 실제 링크 파일이 일치하는지 확인합니다
Info.plist에 필요한 변형이 보이더라도, 실제 링크 대상이 그 변형의 파일인지 확인해야 합니다. 먼저 LibraryIdentifier와 LibraryPath를 따라가 패키지 안의 실제 파일 위치를 찾습니다. 그 뒤 빌드 로그에 나온 링커 입력 경로와 같은 파일인지 비교하십시오.
경로가 일치하지 않으면 오래된 산출물, 캐시된 패키지, 잘못된 검색 경로가 원인일 수 있습니다. 또한 배포 단계에서 목적지 변형이 누락됐는지, 선언은 갱신됐지만 파일은 이전 버전인지 점검합니다. Apple의 XCFramework 생성 안내는 framework와 library를 다중 플랫폼 번들에 포함하는 방법을 설명합니다. 라이브러리의 포장 방식에 맞춰 파일 경로와 선언을 함께 확인하십시오.
필요하다면 Apple의 XCFramework 출처 확인 문서를 사용해 받아 온 패키지의 출처도 점검하십시오. 출처 확인은 플랫폼 호환성 검증을 대신하지 않으므로, 파일의 변형과 아키텍처는 별도로 대조해야 합니다.
자주 묻는 질문
Xcode 27 Beta의 XCFramework 아키텍처 오류는 어디서부터 조사합니까?
실패 타깃과 목적지, 전체 로그를 먼저 고정한 다음 오류가 컴파일, 링크, 실행 중 어디에서 났는지 구분합니다. 이어서 XCFramework의 Info.plist에서 목적지에 맞는 플랫폼 변형을 찾고, 선언된 아키텍처와 실제 파일을 대조하십시오. 이 순서를 따르면 플랫폼 변형 누락과 CPU 아키텍처 누락을 별개 문제로 다룰 수 있습니다. Rosetta 실행을 기본 해결책으로 삼지 마십시오.
iOS Simulator와 실제 기기에서 같은 XCFramework 바이너리를 쓸 수 있습니까?
아키텍처 이름이 같더라도 기기와 시뮬레이터는 서로 다른 플랫폼 변형을 요구할 수 있습니다. 패키지의 SupportedPlatform 및 SupportedPlatformVariant 값을 목적지와 대조하고, 각 항목에 연결된 바이너리도 확인하십시오. 기기 빌드가 성공했다는 사실만으로 Simulator 빌드까지 지원한다고 결론 내리지 마십시오. 필요한 변형이 없다면 호환 패키지를 받거나 소스에서 다시 빌드해야 합니다.
XCFramework가 목표 플랫폼과 아키텍처를 포함하는지 어떻게 확인합니까?
Info.plist의 AvailableLibraries에서 각 항목의 식별자, 플랫폼, 변형, 지원 아키텍처, 파일 경로를 확인합니다. 그런 다음 그 경로의 실제 framework 또는 library 바이너리를 검사하고, 빌드 로그가 같은 파일을 링크했는지 비교하십시오. 선언된 정보와 실제 파일, 실제 링크 입력이 모두 일치해야 합니다. 하나라도 다르면 패키지 생성, 배포, 캐시 또는 검색 경로를 추가로 조사하십시오.
로컬 빌드는 성공하지만 원격 Mac CI에서 링크가 실패하면 어떻게 합니까?
두 환경에서 같은 커밋, 의존성 해석 결과, 빌드 목적지, Xcode 선택을 기록해 비교하십시오. 원격 환경이 다른 의존성 사본이나 오래된 캐시를 쓰는지, 빌드 설정과 링크 경로가 다른지 확인합니다. 로그는 민감한 경로와 인증 정보를 가린 뒤 비교 자료로 보관하십시오. 한 번 성공한 결과만으로 원인을 닫지 말고, 고정한 의존성으로 프로젝트가 지원하는 목적지를 다시 빌드해야 합니다.
다섯째 단계: 원격 Mac CI에서 의존성과 환경 차이를 분리합니다
로컬에서 성공하고 원격 Mac CI에서만 실패한다면, 우선 두 환경이 같은 의존성을 받았는지 확인하십시오. 커밋 식별자뿐 아니라 의존성 잠금 파일, 패키지 출처, 실제 XCFramework 버전과 캐시 사용 여부도 대조합니다. 같은 저장소를 빌드해도 해석된 패키지나 캐시된 산출물이 다르면 결과가 달라질 수 있습니다.
Xcode 선택과 빌드 설정도 함께 기록하십시오. xcodebuild -showBuildSettings로 목적지와 관련된 설정을 확인하고, 로그에서 실제 링크 파일 경로를 찾습니다. 빌드 설정의 의미는 Apple의 Xcode 빌드 설정 참고 자료에서 확인할 수 있습니다. 토큰이나 사용자 정보가 포함된 로그는 가린 뒤 공유하십시오.
비교 결과를 다음처럼 나누면 다음 조치가 선명해집니다.
- 본인 Mac과 CI 모두 같은 변형을 찾지 못하면 의존성 패키지의 변형 누락을 조사합니다.
- 본인 Mac에는 슬라이스가 있지만 CI가 다른 파일을 링크하면 의존성 해석, 검색 경로, 캐시를 조사합니다.
- 선언과 링크 대상은 같은데 CI에서만 실패하면 목적지와 빌드 설정, 선택된 Xcode를 다시 대조합니다.
- 공급자가 필요한 변형을 제공하지 않으면 호환 버전 요청, 소스 재빌드, 업그레이드 보류 중에서 선택합니다.
여섯째 단계: 실제 지원 목적지로 수정 결과를 확인합니다
수정을 끝냈다면 프로젝트가 실제로 지원하는 목적지를 각각 빌드하십시오. 시뮬레이터 빌드만 성공했거나 기기 빌드만 통과한 상태를 전체 검증으로 취급하지 마십시오. 로그에서 최종 앱이 의도한 XCFramework 경로와 변형을 사용했는지도 확인해야 합니다.
아래 표에서 현재 증거와 조치를 대조하십시오.
| 확인 결과 | 문제로 볼 범위 | 다음 조치 |
|---|---|---|
| 목적지에 맞는 플랫폼 변형이 없음 | 패키지 변형 누락 | 공급자에게 호환 패키지를 요청하거나 소스에서 재빌드합니다 |
| 플랫폼 변형은 있으나 아키텍처가 부족함 | 해당 변형의 슬라이스 누락 | 지원 아키텍처를 포함해 다시 빌드하거나 호환 버전을 받습니다 |
| 선언은 맞지만 링크 경로가 다름 | 오래된 산출물, 캐시 또는 검색 경로 | 실제 링크 파일을 추적하고 의존성 해석을 고정합니다 |
| 본인 Mac과 CI의 결과가 다름 | 도구 체인, 설정, 의존성 차이 | 같은 커밋과 의존성으로 두 환경을 재검증합니다 |
| 검증 항목 | 완료 기준 | 미완료일 때의 판단 |
|---|---|---|
| 플랫폼 변형 | 프로젝트가 지원하는 목적지에 대응하는 변형이 선언되어 있습니다 | 의존성 공급자에게 변형 제공 여부를 확인합니다 |
| 아키텍처와 실제 파일 | 선택된 바이너리의 아키텍처가 목적지 요구와 맞습니다 | 해당 변형을 재빌드하거나 호환 패키지를 요청합니다 |
| 링크 경로 | 빌드 로그의 입력 경로와 패키지 선언의 파일 경로가 일치합니다 | 캐시, 검색 경로, 구버전 산출물을 조사합니다 |
| 원격 재현 | 고정한 커밋과 의존성으로 원격 목적지 빌드가 재현됩니다 | 환경 차이를 제거한 뒤 검증을 다시 실행합니다 |