Flutter Apple Silicon Mac에서 iOS 시뮬레이터 XCFramework 빌드 오류 해결하기

🚨 문제 상황

Apple Silicon Mac (M1 이상의 M시리즈)에서 Flutter 앱을 iOS 시뮬레이터로 빌드할 때 다음과 같은 오류를 만나셨나요?

ld: warning: ignoring file
'/path/to/Framework.xcframework/ios-arm64/Framework.framework/Framework':
found architecture 'arm64', required architecture 'arm64'

ld: framework not found Framework

또는 CocoaPods에서:

[!] The following build commands failed:
    PhaseScriptExecution [CP] Copy\ XCFrameworks

💡 이 오류는 해당 라이브러리의 XCFramework가 arm64 시뮬레이터 아키텍처를 지원하지 않기 때문에 발생합니다.

---

🔍 1. 왜 이런 오류가 발생하나요?

iOS 빌드 아키텍처 이해하기

대상	아키텍처	설명
실제 iPhone/iPad	ios-arm64	모든 최신 iOS 기기
Intel Mac 시뮬레이터	ios-x86_64-simulator	Intel 칩 Mac용
Apple Silicon Mac 시뮬레이터	ios-arm64-simulator	M1/M2/M3/M4 Mac용

핵심 문제

2020년 Apple Silicon Mac 출시 이후, iOS 시뮬레이터도 arm64 아키텍처로 동작합니다.

하지만 많은 라이브러리들이 아직 arm64-simulator 슬라이스를 포함하지 않은 XCFramework를 배포하고 있습니다.

기존 XCFramework 구조:
├── ios-arm64/                    ✅ 실제 기기용
└── ios-x86_64-simulator/         ✅ Intel Mac 시뮬레이터용
                                  ❌ arm64-simulator 없음!

---

🛠️ 2. 해결 방법 비교

방법	난이도	장점	단점
Rosetta로 Xcode 실행	⭐	즉시 적용 가능	성능 저하, 근본 해결 아님
라이브러리 이슈 등록	⭐	공식 지원 대기	시간 소요, 대응 불확실
Fork하여 직접 빌드	⭐⭐⭐	완벽한 해결	빌드 지식 필요

---

🚀 3. 방법 1: Rosetta로 Xcode 실행 (임시 해결)

가장 빠른 임시 해결책입니다.

3-1. Xcode를 Rosetta로 실행

Finder에서 Xcode 선택 → 정보 가져오기 → "Rosetta를 사용하여 열기" 체크

3-2. Flutter 빌드

flutter clean
flutter build ios --simulator

⚠️ 주의사항

• 성능이 20~30% 저하됩니다
• 다른 개발 도구와 호환성 문제 가능
• 근본적인 해결책이 아닙니다

---

🔧 4. 방법 2: 라이브러리 Fork 후 직접 빌드 (권장)

arm64 시뮬레이터를 포함한 XCFramework를 직접 빌드하는 방법입니다.

4-1. 현재 XCFramework 아키텍처 확인

# XCFramework 내부 구조 확인
ls -la /path/to/Library.xcframework/

# 각 슬라이스의 아키텍처 확인
lipo -info /path/to/Library.xcframework/ios-arm64/Library.framework/Library
lipo -info /path/to/Library.xcframework/ios-x86_64-simulator/Library.framework/Library

결과 예시:

ios-arm64/Library.framework/Library: arm64
ios-x86_64-simulator/Library.framework/Library: x86_64

❌ ios-arm64-simulator 폴더가 없다면 arm64 시뮬레이터 미지원!

4-2. 소스에서 XCFramework 빌드

라이브러리 소스가 있다면 직접 빌드할 수 있습니다.

#!/bin/bash
# build_xcframework.sh

LIBRARY_NAME="YourLibrary"
OUTPUT_DIR="./output"

# 1. iOS 기기용 빌드 (arm64)
xcodebuild archive \
    -project ${LIBRARY_NAME}.xcodeproj \
    -scheme ${LIBRARY_NAME} \
    -destination "generic/platform=iOS" \
    -archivePath "${OUTPUT_DIR}/ios-device" \
    SKIP_INSTALL=NO \
    BUILD_LIBRARY_FOR_DISTRIBUTION=YES

# 2. iOS 시뮬레이터용 빌드 (arm64 + x86_64)
xcodebuild archive \
    -project ${LIBRARY_NAME}.xcodeproj \
    -scheme ${LIBRARY_NAME} \
    -destination "generic/platform=iOS Simulator" \
    -archivePath "${OUTPUT_DIR}/ios-simulator" \
    SKIP_INSTALL=NO \
    BUILD_LIBRARY_FOR_DISTRIBUTION=YES

# 3. XCFramework 생성
xcodebuild -create-xcframework \
    -framework "${OUTPUT_DIR}/ios-device.xcarchive/Products/Library/Frameworks/${LIBRARY_NAME}.framework" \
    -framework "${OUTPUT_DIR}/ios-simulator.xcarchive/Products/Library/Frameworks/${LIBRARY_NAME}.framework" \
    -output "${OUTPUT_DIR}/${LIBRARY_NAME}.xcframework"

4-3. C/C++ 라이브러리의 경우

C/C++ 소스를 직접 빌드해야 하는 경우:

#!/bin/bash
# C/C++ 라이브러리를 XCFramework로 빌드

LIBRARY_NAME="yourlib"
MIN_IOS_VERSION="12.0"

# iOS 기기용 (arm64)
./configure --host=arm-apple-darwin --enable-static --disable-shared
make clean && make
mkdir -p build/ios-arm64
cp .libs/lib${LIBRARY_NAME}.a build/ios-arm64/

# iOS 시뮬레이터용 (arm64)
SIMULATOR_SDK=$(xcrun --sdk iphonesimulator --show-sdk-path)
./configure --host=arm-apple-darwin --enable-static --disable-shared \
    CFLAGS="-arch arm64 -mios-simulator-version-min=${MIN_IOS_VERSION} -isysroot ${SIMULATOR_SDK}"
make clean && make
mkdir -p build/ios-arm64-simulator
cp .libs/lib${LIBRARY_NAME}.a build/ios-arm64-simulator/

# iOS 시뮬레이터용 (x86_64)
./configure --host=x86_64-apple-darwin --enable-static --disable-shared \
    CFLAGS="-arch x86_64 -mios-simulator-version-min=${MIN_IOS_VERSION} -isysroot ${SIMULATOR_SDK}"
make clean && make
mkdir -p build/ios-x86_64-simulator
cp .libs/lib${LIBRARY_NAME}.a build/ios-x86_64-simulator/

# 시뮬레이터용 Universal 바이너리 생성
mkdir -p build/ios-simulator-universal
lipo -create \
    build/ios-arm64-simulator/lib${LIBRARY_NAME}.a \
    build/ios-x86_64-simulator/lib${LIBRARY_NAME}.a \
    -output build/ios-simulator-universal/lib${LIBRARY_NAME}.a

# XCFramework 생성
xcodebuild -create-xcframework \
    -library build/ios-arm64/lib${LIBRARY_NAME}.a \
    -library build/ios-simulator-universal/lib${LIBRARY_NAME}.a \
    -output output/${LIBRARY_NAME}.xcframework

---

📦 5. Flutter 패키지에 적용하기

5-1. GitHub Fork 생성

1. 원본 패키지 저장소를 Fork
2. 빌드한 XCFramework를 ios/ 폴더에 교체
3. 커밋 및 푸시

5-2. pubspec.yaml 수정

dependencies:
  # 기존 pub.dev 버전 대신 Fork 사용
  your_package:
    git:
      url: https://github.com/YourUsername/your_package.git
      ref: main  # 또는 특정 커밋/태그

5-3. Federated Plugin의 경우

Flutter의 Federated Plugin 구조에서는 platform-specific 패키지도 override해야 합니다.

your_package/              ← 메인 패키지
├── your_package_ios/      ← iOS 구현 (XCFramework 포함)
├── your_package_android/  ← Android 구현
└── your_package_web/      ← Web 구현

workspace root의 pubspec.yaml:

# 루트 pubspec.yaml에서 iOS 구현 패키지를 강제 override
dependency_overrides:
  your_package_ios:
    git:
      url: https://github.com/YourUsername/your_package.git
      path: your_package_ios

5-4. 빌드 확인

단순히 flutter clean만으로는 캐시가 완전히 정리되지 않는 경우가 많습니다. 다음 Makefile 타겟을 사용하면 완벽하게 클린 빌드할 수 있습니다.

Makefile:

clean:
	@echo "🧹 Flutter clean..."
	flutter clean
	flutter pub get
	@echo "🔨 코드 생성 중 (build_runner)..."
	flutter pub run build_runner build --delete-conflicting-outputs
	@echo "🧹 iOS Pods 정리 및 재설치..."
	cd ios && rm -rf Pods && rm -f Podfile.lock && pod cache clean --all
	@echo "🔧 Flutter precache 실행..."
	flutter precache --ios
	@echo "📦 Pod 설치..."
	cd ios && pod install || true

실행:

# Makefile이 있는 프로젝트 루트에서
make clean

# iOS 시뮬레이터 빌드
flutter build ios --simulator --no-codesign

# 성공 메시지 확인
# ✓ Built build/ios/iphonesimulator/Runner.app

💡 왜 이렇게 해야 하나요?

• flutter clean: Flutter 빌드 캐시 삭제
• build_runner: 코드 생성 파일 재생성 (freezed, json_serializable 등)
• rm -rf Pods && pod cache clean --all: CocoaPods 캐시 완전 삭제
• flutter precache --ios: iOS 빌드 아티팩트 사전 다운로드
• pod install: 수정된 XCFramework로 Pod 재설치

---

🔎 6. 트러블슈팅

Q1. dependency_overrides가 적용되지 않아요

원인: Pub Workspace 환경에서는 루트 pubspec.yaml에 override를 추가해야 합니다.

# 프로젝트 루트 pubspec.yaml
dependency_overrides:
  your_package_ios:
    git:
      url: https://github.com/YourUsername/your_package.git
      path: your_package_ios

Q2. symlink가 여전히 pub.dev를 가리켜요

해결:

# pub 캐시에서 해당 패키지 삭제
rm -rf ~/.pub-cache/hosted/pub.dev/your_package*

# Makefile로 완전 클린 빌드 (위 섹션 5-4 참고)
make clean

# symlink 확인
ls -la ios/.symlinks/plugins/your_package_ios

Q3. "framework not found" 오류가 계속돼요

확인 사항:

# XCFramework 슬라이스 확인
ls ios/.symlinks/plugins/your_package_ios/ios/*.xcframework/

# 예상 결과:
# ios-arm64/
# ios-arm64_x86_64-simulator/  ← 또는 ios-arm64-simulator/ + ios-x86_64-simulator/

---

📋 7. 체크리스트

빌드 전 확인사항:

• XCFramework에 ios-arm64-simulator 슬라이스 포함 확인
• Fork된 저장소에 수정사항 푸시 완료
• pubspec.yaml에서 git dependency로 변경
• Federated Plugin의 경우 dependency_overrides 추가
• make clean 실행 (또는 수동으로 Flutter + Pods 캐시 정리)
• .symlinks 경로가 Fork를 가리키는지 확인

---

🎯 8. 마무리

Apple Silicon Mac에서 iOS 시뮬레이터 빌드 오류는 많은 Flutter 개발자들이 겪는 문제입니다.

라이브러리 관리자에게 arm64 시뮬레이터 지원을 요청하는 것이 가장 좋지만, 급하다면 이 가이드를 따라 직접 해결할 수 있습니다.

핵심 요약

1. 🔍 XCFramework 아키텍처 슬라이스 확인
2. 🛠️ arm64-simulator 포함하여 재빌드
3. 📦 Fork 생성 후 pubspec.yaml에서 git dependency 사용
4. ⚙️ Federated Plugin은 dependency_overrides 필수

---

도움이 되셨다면 좋아요 👍 부탁드립니다!

궁금한 점은 댓글로 남겨주세요 😊