Tuesday, February 2, 2021

Flutter iOS 빌드 지옥 탈출: IPHONEOS_DEPLOYMENT_TARGET 오류 완벽 해결 가이드
  /   No comments   

Flutter로 열심히 개발한 앱, 시뮬레이터에서는 완벽하게 작동하는데 막상 실제 iOS 기기에 빌드하거나 App Store 배포를 위해 아카이빙을 시도하는 순간, 개발자의 발목을 잡는 붉은색 에러 메시지를 마주할 때가 있습니다. 그중에서도 가장 악명 높고 많은 개발자들을 좌절하게 만드는 오류가 바로 'IPHONEOS_DEPLOYMENT_TARGET' 관련 문제입니다. 아마 이 글을 찾아오신 분들이라면 아래와 같은 메시지에 익숙하실 겁니다.

IPHONEOS_DEPLOYMENT_TARGET 오류 발생 화면
 

Error: The plugin "some_package" requires a higher minimum iOS deployment target.
...
deployment target 'IPHONEOS_DEPLOYMENT_TARGET' is set to 9.0, but the range of supported deployment target version is 11.0 to 16.2.
...

이 오류는 단순히 Xcode 설정을 바꾼다고 해결되지 않는 경우가 대부분입니다. 구글링을 통해 찾은 단편적인 해결책들, 예를 들어 Xcode에서 직접 버전을 수정하는 방법은 임시방편에 그치거나 Flutter의 빌드 시스템에 의해 다시 덮어씌워져 무용지물이 되기 일쑤입니다. 이로 인해 수많은 개발자들이 귀중한 시간을 '삽질'에 허비하곤 합니다.

이 글에서는 IPHONEOS_DEPLOYMENT_TARGET 오류의 근본적인 원인을 깊이 파헤치고, 일시적인 해결이 아닌 완벽하고 체계적인 해결 전략을 제시합니다. 이 가이드를 끝까지 따라오신다면, 다시는 이 오류 때문에 스트레스받는 일은 없을 것이라고 확신합니다.

1. 'IPHONEOS_DEPLOYMENT_TARGET'의 정체: 왜 이 오류가 발생할까?

문제를 해결하려면 먼저 적을 알아야 합니다. IPHONEOS_DEPLOYMENT_TARGET은 Xcode 프로젝트 설정의 한 부분으로, "이 앱이 최소한으로 지원하는 iOS 버전"을 의미합니다. 예를 들어, 이 값을 '12.0'으로 설정하면 해당 앱은 iOS 12.0 미만 버전이 설치된 아이폰에서는 설치하거나 실행할 수 없습니다.

그렇다면 오류는 왜 발생할까요? 오류 메시지 "deployment target 'IPHONEOS_DEPLOYMENT_TARGET' is set to 9.0, but the range of supported deployment target version is 11.0 to 16.2"를 분석해 봅시다.

  • 'set to 9.0': 내 프로젝트 어딘가에(주로 내가 사용 중인 패키지 중 하나) 최소 지원 버전을 iOS 9.0으로 설정한 부분이 있다는 의미입니다.
  • 'range of supported ... is 11.0 to 16.2': 내가 현재 사용하고 있는 Xcode 버전이 지원하는 최소 iOS 버전은 11.0이라는 의미입니다. 즉, Xcode가 너무 최신이라 iOS 9.0 같은 구버전용으로 앱을 빌드해 줄 수 없다는 뜻입니다.

이것을 비유하자면, 최신 Windows 11 운영체제에서 90년대에 만들어진 DOS 전용 프로그램을 실행하려는 것과 같습니다. 운영체제가 너무 발전해서 더 이상 구형 프로그램을 위한 환경을 지원하지 않는 것이죠. Xcode와 iOS의 관계도 마찬가지입니다. Apple은 새로운 Xcode를 출시할 때마다 점차적으로 오래된 iOS 버전에 대한 지원을 중단합니다.

Flutter 프로젝트에서 이 문제가 복잡한 이유

네이티브 iOS 앱 개발에서는 이 값을 한 곳에서만 관리하면 되지만, Flutter는 다릅니다. Flutter 프로젝트의 iOS 부분은 여러 조각으로 구성되어 있습니다.

  1. 메인 프로젝트 (Runner): ios/Runner.xcworkspace로 열리는 우리 앱의 기본 뼈대입니다.
  2. Flutter 프레임워크: Flutter 엔진 자체도 특정 iOS 버전을 요구합니다.
  3. 네이티브 코드를 포함한 플러그인 (Packages): pubspec.yaml에 추가한 수많은 패키지들(카메라, 위치 정보, 파이어베이스 등)은 각자 독립적인 네이티브 iOS 코드를 가지고 있으며, 자신만의 최소 지원 버전을 명시하고 있습니다. 이것이 문제의 핵심 원인인 경우가 많습니다.

결과적으로 Flutter iOS 빌드 과정은 이 모든 조각들의 최소 지원 버전 요구사항을 하나로 합치는 과정입니다. 이때 하나의 조각이라도 현재 Xcode가 지원하지 않는 너무 낮은 버전을 요구하면, CocoaPods(iOS의 의존성 관리 도구)가 버전 충돌을 감지하고 빌드를 중단시키는 것입니다.

2. 흔히 알려진 해결책과 그 명백한 한계

이 오류를 검색하면 가장 먼저 접하게 되는 몇 가지 해결책이 있습니다. 하지만 왜 이것들이 근본적인 해결책이 되지 못하는지 이해하는 것이 중요합니다.

한계 1: Xcode에서 직접 Deployment Target 수정하기

가장 직관적인 방법입니다. ios/Runner.xcworkspace를 Xcode로 열고, 왼쪽 네비게이터에서 'Runner'를 선택한 뒤 'General' 탭의 'Deployment Info' > 'Target'에서 버전을 직접 수정하는 것입니다.

왜 효과가 없는가?

이 방법은 내 메인 프로젝트(Runner)의 타겟 버전만 바꿀 뿐, 수많은 외부 패키지(플러그인)들의 타겟 버전은 전혀 건드리지 못합니다. 문제의 원인이 오래된 패키지에 있다면 이 방법은 아무런 효과가 없습니다. 설상가상으로, flutter clean이나 flutter pub get 명령어를 실행하면 Flutter의 빌드 스크립트가 이 설정을 다시 원래대로 덮어써 버리는 경우도 비일비재합니다.

한계 2: Podfile에서 플랫폼 버전 수정하기

조금 더 나아간 방법은 ios/Podfile을 직접 수정하는 것입니다. Podfile 상단에는 다음과 같은 라인이 있습니다.


# Uncomment this line to define a global platform for your project
# platform :ios, '11.0'

이 부분의 주석(#)을 해제하고 버전을 명시적으로 설정한 뒤, 터미널에서 ios 폴더로 이동해 pod install 명령어를 실행하는 방법입니다.

왜 이것만으로는 부족한가?

이 설정은 모든 Pod(패키지)들이 따라야 할 '권장' 버전을 제시하는 것과 같습니다. 대부분의 잘 만들어진 패키지들은 이 설정을 존중하여 자신의 버전을 맞춥니다. 하지만 일부 오래되거나 관리가 잘 안 되는 패키지는 이 전역 설정을 무시하고 자신만의 구버전 설정을 고집하는 경우가 있습니다. 이 경우 여전히 버전 충돌이 발생하여 빌드에 실패하게 됩니다.

3. 진짜 원인 파헤치기: `pubspec.yaml` 속 범인 찾기

앞서 설명했듯이, 이 문제의 90% 이상은 pubspec.yaml에 추가한 특정 패키지 때문에 발생합니다. Flutter의 장점인 풍부한 생태계가 때로는 이런 문제를 일으키는 양날의 검이 되는 셈입니다.

모든 네이티브 플러그인은 자신만의 .podspec 파일을 가지고 있습니다. 이 파일 안에 s.platform = :ios, '9.0' 과 같은 코드로 자신의 최소 지원 버전을 명시합니다. 만약 여러분이 50개의 패키지를 사용한다면, 50개의 각기 다른 최소 버전 요구사항이 존재할 수 있는 것입니다.

flutter pub get 명령이 실행될 때, CocoaPods는 이 모든 .podspec 파일들을 읽어와 의존성을 해결하려고 시도합니다. 이때 단 하나의 패키지라도 현재 Xcode가 지원하는 최소 버전(예: 11.0)보다 낮은 버전(예: 9.0)을 요구하면, CocoaPods는 "이 오래된 패키지 때문에 프로젝트 전체를 빌드할 수 없습니다!"라며 오류를 뱉어내는 것입니다.

따라서, 문제 해결의 핵심은 내 프로젝트의 설정을 바꾸는 것이 아니라, 문제를 일으키는 특정 패키지를 찾아내어 조치하는 것에 있습니다.

4. 단계별 완벽 해결 전략: 이 순서대로만 따라 하세요

이제 이론은 충분합니다. 아래의 단계별 전략을 순서대로 따라 하면 어떤 상황에서든 문제를 해결할 수 있습니다.

1단계: Podfile 후크(Hook)로 모든 패키지 버전 강제 통일하기

가장 먼저 시도해야 할 가장 강력하고 효과적인 방법입니다. 이는 각 패키지가 제멋대로 설정한 최소 버전을 무시하고, 우리 프로젝트의 Podfile이 모든 패키지의 버전을 강제로 덮어쓰도록 만드는 방법입니다.

1. 프로젝트의 ios/Podfile 파일을 엽니다. 2. 파일의 맨 끝, end 바로 위에 아래 코드를 그대로 복사하여 붙여넣습니다.


post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
    target.build_configurations.each do |config|
      config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '12.0' # <-- 이 버전을 원하는 최소 버전으로 수정하세요.
    end
  end
end

코드 설명:

  • post_install do |installer|: CocoaPods가 모든 패키지(Pod) 설치를 마친 후에 이 코드를 실행하라는 의미입니다.
  • installer.pods_project.targets.each do |target|: 설치된 모든 패키지를 하나씩 순회합니다.
  • config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '12.0': 각 패키지의 빌드 설정으로 직접 들어가 IPHONEOS_DEPLOYMENT_TARGET 값을 우리가 지정한 버전(여기서는 '12.0')으로 강제로 덮어씌웁니다.

중요: '12.0' 부분은 여러분의 프로젝트가 지원해야 할 최소 iOS 버전으로 설정해야 합니다. 일반적으로 현재 (2023년 기준) iOS 12.0 또는 13.0 정도면 대부분의 사용자를 커버할 수 있습니다. 오류 메시지에 나온 지원 가능 범위(예: 11.0 to 16.2) 내의 값으로 설정해야 합니다.

3. 파일을 저장한 뒤, 터미널을 열고 프로젝트의 `ios` 폴더로 이동합니다.


cd ios
4. 기존 Pod 설정을 완전히 지우고 새로 설치하기 위해 아래 명령어를 차례로 실행합니다. (만약 pod deintegrate가 설치되어 있지 않다면 pod install만 실행해도 괜찮습니다.) 

pod deintegrate
pod install --repo-update
5. 이제 다시 Flutter 프로젝트 루트 폴더로 돌아가서 빌드를 시도합니다. 

cd ..
flutter clean
flutter build ipa

대부분의 경우, 이 1단계만으로 문제가 거짓말처럼 해결됩니다. 이 방법은 개별 패키지의 설정을 일일이 찾아다닐 필요 없이 중앙에서 모든 것을 통제하는 가장 확실한 해결책입니다.

2단계: 범인 패키지 색출하기 (1단계로 해결되지 않을 경우)

만약 1단계의 방법으로도 오류가 계속 발생한다면, 이는 특정 패키지가 매우 오래되었거나 post_install 후크와 충돌하는 특이한 설정을 가지고 있을 가능성이 높습니다. 이제 탐정이 되어 범인을 찾아내야 합니다.

이 과정은 프로젝트의 pubspec.yaml 파일에 있는 의존성(dependencies) 목록을 하나씩 제거해보며 원인이 되는 패키지를 찾는 것입니다. 패키지가 많다면 '이진 탐색(Binary Search)' 방법을 사용하는 것이 효율적입니다.

1. pubspec.yaml 파일을 엽니다. 2. dependencies: 아래에 있는 패키지 목록의 절반을 주석 처리(#)합니다. 


dependencies:
  flutter:
    sdk: flutter

  cupertino_icons: ^1.0.2
  firebase_core: ^2.15.0
  firebase_auth: ^4.7.0
  cloud_firestore: ^4.8.0
  # provider: ^6.0.5
  # http: ^1.1.0
  # shared_preferences: ^2.2.0
  # path_provider: ^2.1.0
3. 터미널에서 flutter pub get을 실행하여 변경사항을 적용합니다. 4. 다시 iOS 빌드를 시도합니다. (ios 폴더에서 pod install 후 빌드) 5. 판단:
  • 오류가 사라졌다면? 범인은 방금 주석 처리한 패키지 그룹 안에 있습니다.
  • 오류가 여전히 발생한다면? 범인은 주석 처리하지 않은 나머지 패키지 그룹 안에 있습니다.
6. 범인이 속한 그룹을 찾았다면, 그 그룹 내에서 다시 절반을 주석 처리하거나 해제하며 과정을 반복합니다. 7. 이 과정을 계속 반복하면 결국 단 하나의 범인 패키지를 특정할 수 있습니다.

이 방법은 다소 시간이 걸릴 수 있지만, 어떤 패키지가 문제의 근원인지 100% 확실하게 찾아낼 수 있는 방법입니다.

3단계: 문제 패키지 해결하기

범인을 찾았다면, 이제 처방을 내릴 시간입니다. 해결책은 여러 가지가 있습니다.

  • A) 패키지 업데이트: 가장 먼저 시도할 방법입니다. 오래된 버전의 패키지가 문제를 일으키는 경우가 많습니다. pub.dev에서 해당 패키지를 검색하여 최신 버전이 있는지 확인하고, 있다면 pubspec.yaml의 버전 명세를 최신으로 수정하거나 flutter pub upgrade [패키지이름] 명령어로 업데이트합니다. 최신 버전에서는 최소 iOS 지원 버전이 상향 조정되어 문제가 해결되었을 가능성이 높습니다.
  • B) 패키지 다운그레이드: 오히려 최신 버전의 패키지가 너무 높은 iOS 버전을 요구해서 문제가 될 수도 있습니다. 이 경우, 한두 단계 낮은 안정적인 버전으로 다운그레이드하여 테스트해 봅니다.
  • C) 대안 패키지 찾기: 만약 해당 패키지가 오랫동안 업데이트되지 않고 방치된 '유령 패키지'라면, 과감하게 포기하고 동일한 기능을 하는 다른 최신 패키지를 찾아 교체하는 것이 장기적으로 훨씬 좋습니다.
  • D) (최후의 수단) 패키지 Fork 및 직접 수정: 해당 패키지가 꼭 필요하지만 관리가 안 되고 대안도 없다면, GitHub에서 해당 패키지의 소스 코드를 Fork(복제)한 뒤, 직접 .podspec 파일의 s.platform = :ios, '9.0' 같은 부분을 수정합니다. 그리고 pubspec.yaml에서 pub.dev 버전 대신 여러분이 수정한 GitHub 저장소 주소를 사용하도록 설정할 수 있습니다. 이는 상당한 전문 지식을 요구하는 고급 해결책입니다. 
    
dependencies:
  some_package:
    git:
      url: https://github.com/your_username/some_package.git
      ref: main

5. 예방 및 모범 사례: 다시는 같은 실수를 반복하지 않기 위해

문제를 해결하는 것도 중요하지만, 앞으로 이런 문제를 예방하는 것은 더 중요합니다. 몇 가지 습관만으로도 iOS 빌드 오류의 공포에서 벗어날 수 있습니다.

  1. `Podfile` 후크를 기본으로 사용하세요: 새로운 Flutter 프로젝트를 시작할 때마다, 위 4장의 1단계에서 소개한 post_install 코드를 ios/Podfile에 미리 추가해두는 습관을 들이세요. 이것만으로도 90%의 `IPHONEOS_DEPLOYMENT_TARGET` 관련 문제를 예방할 수 있습니다.
  2. 정기적으로 의존성을 확인하고 업데이트하세요: 터미널에서 flutter pub outdated 명령어를 실행하면 현재 사용 중인 패키지 중 업데이트가 가능한 목록을 보여줍니다. 정기적으로 이 명령을 실행하여 패키지를 최신 상태로 유지하면 오래된 패키지로 인한 문제를 사전에 방지할 수 있습니다.
  3. 새로운 패키지 추가 시 신중하세요: 새로운 패키지를 추가할 때는 pub.dev에서 해당 패키지의 'Versions' 탭을 확인하여 최근까지 꾸준히 업데이트가 되고 있는지, 'Issues' 탭에 비슷한 빌드 문제가 보고되지는 않았는지 확인하는 것이 좋습니다. 인기가 많고 관리가 잘 되는 패키지를 선택하는 것이 안전합니다.

결론: 이제 당신은 iOS 빌드 전문가입니다

IPHONEOS_DEPLOYMENT_TARGET 오류는 Flutter 개발 여정에서 누구나 한 번쯤 마주치는 거대한 벽처럼 느껴질 수 있습니다. 하지만 이제 여러분은 이 벽의 정체가 무엇인지, 그리고 어떻게 체계적으로 무너뜨릴 수 있는지 알게 되었습니다.

다시 한번 핵심을 요약하자면 다음과 같습니다.

  • 원인: 프로젝트에 포함된 여러 패키지(플러그인)들의 최소 iOS 지원 버전 요구사항이 제각각이고, 그중 하나라도 현재의 Xcode가 지원하지 않는 너무 낮은 버전을 요구하기 때문에 발생합니다.
  • 최고의 해결책: ios/Podfile에 post_install 후크를 추가하여 모든 패키지의 버전을 중앙에서 강제로 통일하는 것입니다.
  • 차선책: 후크로 해결되지 않을 경우, `pubspec.yaml`의 의존성을 하나씩 점검하여 문제의 원인이 되는 패키지를 찾아내고 업데이트, 교체 등의 조치를 취합니다.

더 이상 단편적인 정보에 의존해 시간을 낭비하지 마세요. 이 가이드에서 제시한 체계적인 접근법을 통해 여러분은 어떤 `IPHONEOS_DEPLOYMENT_TARGET` 오류 상황에서도 자신감 있게 대처할 수 있는 능력을 갖추게 되었습니다. 이제 다시 코드로 돌아가 멋진 앱을 완성하는 데 집중하시기 바랍니다. 행복한 코딩 되세요!


0 개의 댓글:

Post a Comment