beautifulsoups.dev
Published on

Flutter iOS 빌드 실패? Pods·Xcode 15 해결

Authors

서론

Flutter로 iOS 빌드를 하다 보면 Android는 멀쩡한데 iOS만 갑자기 깨지는 순간이 자주 옵니다. 특히 Xcode 15로 올라오면서 iOS SDK, 빌드 시스템, 시뮬레이터 아키텍처, 서명 정책 등이 함께 바뀌어 pod install이 잘 되던 프로젝트도 어느 날부터 실패하는 경우가 많습니다.

이 글은 Flutter iOS 빌드 실패를 “Pods(CocoaPods) 단계”와 “Xcode 빌드 단계”로 나눠, 로그에서 자주 보이는 패턴별로 원인을 좁히고, 재현 가능한 해결 절차(클린, Pod 재설치, 설정 수정, Xcode 15 대응)를 정리합니다.

관련해서 CocoaPods 설치 자체가 안 되어 있는 케이스는 아래 글도 함께 참고하면 좋습니다.

문제를 분류하는 가장 빠른 방법: 실패 지점부터

iOS 빌드 실패는 대개 아래 둘 중 하나입니다.

  1. pod install 혹은 pod repo update 단계에서 실패
  • 예: CocoaPods could not find compatible versions for pod ...
  • 예: Specs satisfying the ... dependency were found, but they required a higher minimum deployment target
  • 예: ffi / xcodeproj / Ruby 관련 오류
  1. Pods 설치는 되지만 Xcode 빌드에서 실패
  • 예: Sandbox: rsync ... deny
  • 예: Building for iOS Simulator, but linking in object file built for iOS
  • 예: Undefined symbols for architecture arm64
  • 예: The sandbox is not in sync with the Podfile.lock

먼저 아래 명령으로 “Pod 단계”와 “Xcode 단계”를 분리해서 로그를 확보하세요.

# 1) Flutter 캐시/빌드 산출물 정리
flutter clean

# 2) iOS 의존성 정리
rm -rf ios/Pods ios/Podfile.lock

# 3) Pod 설치(여기서 실패하면 Pods 문제)
cd ios
pod install --repo-update

# 4) 다시 루트로 돌아와 빌드(여기서 실패하면 Xcode 설정/링크 문제)
cd ..
flutter build ios -v

이제부터는 “자주 터지는 원인”을 로그 패턴에 맞춰 해결합니다.

Pods 단계에서 실패할 때

1) minimum deployment target 불일치

Xcode 15 + 최신 iOS SDK 조합에서, 일부 Pod가 더 높은 iOS 최소 버전을 요구하는 경우가 있습니다. 이때는 Podfile의 플랫폼 버전을 올리고, Flutter 쪽 iOS 최소 버전도 맞춰야 합니다.

ios/Podfile에서 다음을 확인하세요.

platform :ios, '12.0'

필요하다면 예를 들어 13.0 또는 프로젝트 요구에 맞게 올립니다.

platform :ios, '13.0'

변경 후에는 반드시 Pod를 다시 설치합니다.

cd ios
rm -rf Pods Podfile.lock
pod install --repo-update

추가로 ios/Runner.xcodeproj 혹은 Runner.xcworkspace의 Deployment Target도 Xcode에서 동일하게 맞춰야 “설치 성공, 빌드 실패”를 줄일 수 있습니다.

2) The sandbox is not in sync with the Podfile.lock

이 메시지는 보통 “Podfile.lock과 실제 Pods 폴더 상태가 어긋났다”는 뜻입니다. 가장 확실한 해결은 Pods와 lock을 함께 지우고 재설치입니다.

cd ios
rm -rf Pods Podfile.lock
pod install

CI에서만 발생한다면, 캐시된 Pods 디렉터리를 복원하고 Podfile.lock만 갱신되는 식의 파이프라인 문제가 있을 수 있습니다. 이 경우는 캐시 키를 Podfile.lock 해시 기반으로 바꾸는 방식이 안정적입니다.

3) Ruby/CocoaPods/Xcodeproj 버전 충돌

Xcode 15 환경에서는 cocoapods와 xcodeproj 조합이 구버전이면 설치 단계에서 애매한 에러가 납니다. 대표적으로 Ruby 기본 버전과 gem 충돌이 원인인 경우가 많습니다.

가장 단순한 확인:

ruby -v
pod --version
gem list cocoapods

업데이트(환경에 따라 sudo가 필요할 수 있음):

gem install cocoapods
pod repo update

프로젝트 단위로 버전을 고정하고 싶다면 Bundler를 쓰는 것이 안전합니다.

cd ios
bundle init
bundle add cocoapods
bundle exec pod install

이렇게 하면 팀원/CI가 동일한 CocoaPods 버전으로 설치해 재현성이 좋아집니다.

Xcode 15에서 빌드 단계가 실패할 때

1) Sandbox: rsync ... deny (Xcode 15에서 특히 빈번)

Xcode 15에서는 빌드 과정에서 rsync가 특정 경로 접근을 차단당하는 케이스가 늘었습니다. 흔히 flutter build ios 또는 Xcode 빌드 중에 아래와 유사한 로그가 나옵니다.

  • Sandbox: rsync(...) deny(1) file-read-data ...

해결 방향은 “빌드 스크립트/리소스 복사 단계가 샌드박스 정책에 걸리지 않게” 만드는 것입니다. 실무에서 가장 많이 쓰는 우회는 다음 중 하나입니다.

  1. Xcode에서 Runner 타겟의 Build Phases에 있는 Flutter 관련 스크립트(예: Thin Binary, Copy Flutter Framework) 실행 순서/입력 경로를 점검
  2. DerivedData 삭제 후 재빌드
rm -rf ~/Library/Developer/Xcode/DerivedData
flutter clean
cd ios && pod install && cd ..
flutter build ios
  1. 문제가 특정 Pod의 리소스 복사 단계에서만 재현되면, 해당 Pod 업데이트 또는 대체 버전 적용

이 이슈는 프로젝트마다 트리거가 달라 “한 줄로 고치는 정답”이 잘 없습니다. 하지만 DerivedData 삭제와 Pods 재설치를 함께 하면 상당수는 해결됩니다.

2) 시뮬레이터 아키텍처 문제: linking in object file built for iOS

Apple Silicon 환경에서 시뮬레이터는 기본적으로 arm64로 도는 경우가 많고, 일부 바이너리/프레임워크가 x86_64 또는 디바이스 전용으로만 제공되면 다음 같은 오류가 납니다.

  • Building for iOS Simulator, but linking in object file built for iOS
  • Undefined symbols for architecture arm64

해결은 “어떤 대상(시뮬레이터/디바이스)에서 빌드하는지”를 먼저 확정하고, 그에 맞는 바이너리를 쓰는 것입니다.

  • 디바이스 빌드가 목적이라면: flutter build ios로 디바이스 타겟만 빌드
  • 시뮬레이터 실행이 목적이라면: 문제가 되는 SDK가 시뮬레이터용 아키텍처를 지원하는지 확인(업데이트가 정답인 경우가 많음)

임시로 시뮬레이터에서만 arm64를 제외하는 방식도 있지만, 이는 근본 해결이 아니라 “로컬 개발 편의” 수준으로만 권장합니다. 적용 위치는 Xcode의 Build Settings에서 Excluded Architectures를 조정합니다.

주의: Xcode 설정 화면에서 부등호가 포함된 텍스트를 그대로 붙여넣는 경우가 있는데, 문서/위키에 공유할 때는 arm64 같은 값만 코드로 남기고, 비교 기호가 들어간 표기(예: x86_64 -> arm64)는 반드시 인라인 코드로 감싸는 습관이 안전합니다.

3) Flutter.framework not found 또는 Pods-Runner 관련 링크 실패

Pod 설치는 됐는데 링크 단계에서 실패하면 다음을 점검합니다.

  1. 반드시 Runner.xcworkspace로 열었는지

CocoaPods를 쓰는 프로젝트는 Runner.xcodeproj가 아니라 Runner.xcworkspace로 열어야 Pod가 연결됩니다.

  1. ios/Flutter/Generated.xcconfig가 생성되어 있는지

이 파일이 없으면 Flutter가 iOS 빌드 설정을 제대로 주입하지 못한 상태일 수 있습니다.

flutter pub get
flutter clean
flutter build ios
  1. pod install이 성공했는지, 그리고 워크스페이스에 Pods 프로젝트가 포함되는지
cd ios
pod install
open Runner.xcworkspace

4) 코드 서명/프로비저닝 이슈 (Xcode 15에서 더 엄격하게 체감)

에러 예시는 다음과 같습니다.

  • No profiles for ... were found
  • Signing for ... requires a development team

해결은 Xcode의 Signing & Capabilities에서 팀을 지정하고, 번들 ID가 Apple Developer에 등록되어 있는지 확인하는 정석 루트가 가장 빠릅니다.

CI라면 ExportOptions.plist와 인증서/프로비저닝 자동화(예: fastlane match)를 점검해야 합니다.

“한 번에” 정리하는 추천 해결 순서

여러 원인이 얽혀 있을 때는 아래 순서가 시간 낭비를 줄입니다.

1) 도구 버전 확인

flutter --version
xcodebuild -version
pod --version
ruby -v

Xcode 15인데 CocoaPods가 너무 오래된 경우가 특히 위험합니다.

2) Flutter/iOS 산출물 초기화

flutter clean
rm -rf ios/Pods ios/Podfile.lock
rm -rf ~/Library/Developer/Xcode/DerivedData

3) Pod 재설치

cd ios
pod install --repo-update
cd ..

4) 워크스페이스로 열어 빌드

open ios/Runner.xcworkspace

Xcode에서 직접 Runner 스킴을 빌드해 로그를 보고, 같은 실패가 flutter build ios -v에서도 재현되는지 확인합니다.

5) 그래도 안 되면: “최소 iOS 버전”과 “문제 Pod”를 좁히기

  • minimum deployment target 관련 로그가 있으면 platform :ios 상향
  • 아키텍처 링크 오류면 해당 SDK/Pod 업데이트 여부 확인
  • rsync deny면 DerivedData 삭제 + Pod 업데이트 + 빌드 스크립트/리소스 복사 단계 점검

트러블슈팅 체크리스트 (현장용)

  • pod install이 실패하는가, Xcode 빌드에서 실패하는가
  • Runner.xcworkspace로 열었는가
  • ios/Pods, ios/Podfile.lock, DerivedData를 모두 지우고 재시도했는가
  • Podfile의 platform :ios 버전이 최신 Pod 요구사항과 맞는가
  • 시뮬레이터/디바이스 아키텍처 불일치 로그가 있는가 (arm64, x86_64)
  • 코드 서명(Team, Bundle ID, 프로비저닝) 설정이 맞는가

마무리

Flutter iOS 빌드는 “Pods 설치가 성공했는지”와 “Xcode 15 빌드 정책/아키텍처 변화에 걸린 건 아닌지”만 분리해도 해결 속도가 크게 빨라집니다. 특히 Xcode 15 업그레이드 이후에는 DerivedData, Pods, lock 파일을 한 번에 정리하고 pod install --repo-update로 재구성하는 루틴이 가장 확률 높은 1차 처방입니다.

만약 에러 로그가 애매하게 섞여 있다면, 실패 지점(설치 단계 vs 링크/서명 단계)을 먼저 확정한 뒤 위 체크리스트 순서대로 하나씩 제거해 보세요. 로그 한 줄만 정확히 잡아도 원인은 대부분 “최소 iOS 버전”, “아키텍처”, “워크스페이스”, “서명” 중 하나로 수렴합니다.

Discuss on Twitter • View on GitHub