beautifulsoups.dev
Published on

Flutter iOS 빌드 No such module 10분 해결

Authors

Flutter로 iOS 빌드를 하다 보면 어느 날 갑자기 No such module 'XXX' 같은 에러가 터집니다. 특히 플러그인을 추가하거나, Xcode를 업그레이드했거나, CI에서만 실패하는 경우가 많습니다. 이 에러는 “모듈을 찾을 수 없다”는 단순 메시지지만, 실제 원인은 대부분 Pods 통합이 깨졌거나, 빌드 설정이 꼬였거나, 캐시/아키텍처 문제입니다.

이 글은 10분 안에 해결하는 것을 목표로, 가장 성공 확률이 높은 순서대로 정리합니다.

0) 먼저 에러의 형태를 분류하기

대표적으로 아래 중 하나로 나타납니다.

  • No such module 'FirebaseCore'
  • No such module 'Flutter'
  • No such module 'SomePlugin'
  • Module 'XXX' not found

핵심은 “어떤 타겟에서, 어떤 방식으로 모듈을 못 찾는지”입니다.

  • Xcode에서만 실패: 워크스페이스/빌드 설정 문제일 확률이 큼
  • flutter build ios 에서 실패: Pods 통합 또는 캐시 문제일 확률이 큼
  • CI에서만 실패: 캐시 충돌, CocoaPods repo 미갱신, Xcode 버전 차이 가능성이 큼

CI 캐시가 원인인 경우는 디버깅 패턴이 비슷합니다. 캐시 이슈 전개 방식은 GitHub Actions 캐시 충돌로 CI 간헐 실패 디버깅 글의 접근법이 그대로 도움이 됩니다.

1) 1분 컷: Xcode에서 .xcworkspace 로 열었는지 확인

CocoaPods를 쓰는 iOS 프로젝트는 반드시 ios/Runner.xcworkspace 로 열어야 합니다.

  • 잘못된 예: ios/Runner.xcodeproj 를 열고 빌드
  • 올바른 예: ios/Runner.xcworkspace 를 열고 빌드

.xcodeproj 로 열면 Pods가 링크되지 않아 No such module 이 가장 흔하게 발생합니다.

확인 방법

터미널에서 아래로 열어도 됩니다.

open ios/Runner.xcworkspace

2) 3분 컷: Pods 재설치(가장 성공률 높음)

대부분은 Pods가 깨졌거나, Podspec/lock이 꼬였거나, DerivedData가 오래된 상태입니다. 아래 순서로 “깨끗한 재생성”을 합니다.

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

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

flutter pub get

포인트

  • pod install --repo-update 는 특히 Firebase 계열이나 최신 Pod 업데이트가 필요한 경우 효과가 큽니다.
  • DerivedData 삭제는 Xcode가 이전 모듈 인덱스/캐시를 붙잡고 있을 때 결정타가 됩니다.

3) use_frameworks! / use_modular_headers! 충돌 점검

Flutter 플러그인 조합에 따라 Podfile 설정이 맞지 않으면 Swift 모듈 임포트가 실패하며 No such module 로 보일 수 있습니다.

대표적인 케이스

  • 특정 Pod는 정적 라이브러리로 붙어야 하는데 프레임워크로 붙어서 모듈이 꼬임
  • Swift 플러그인이 모듈 헤더를 기대하는데 헤더 설정이 불일치

ios/Podfile 에서 아래 블록을 확인합니다.

platform :ios, '12.0'

# 필요 시에만 사용. 무작정 추가하면 다른 Pod와 충돌할 수 있음.
# use_frameworks!
# use_modular_headers!

target 'Runner' do
  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
end

빠른 판단 기준

  • 에러가 Firebase/GoogleUtilities 쪽에서 자주 터진다: use_frameworks! 조합 이슈가 잦습니다.
  • 에러가 특정 Swift 플러그인 모듈에서만 난다: use_modular_headers! 또는 해당 Pod의 모듈맵 문제일 수 있습니다.

가장 안전한 접근은 “변경 전 상태로 되돌린 뒤, 필요한 플러그인의 공식 문서가 요구하는 설정만 최소 적용”입니다.

4) No such module 'Flutter' 인 경우: Generated.xcconfig 누락 점검

이 케이스는 Pods 문제가 아니라 Flutter iOS 빌드 산출물/경로가 깨졌을 때 자주 발생합니다.

다음을 확인하세요.

  • ios/Flutter/Generated.xcconfig 파일 존재 여부
  • ios/Flutter/flutter_export_environment.sh 파일 존재 여부

없다면 아래로 재생성합니다.

flutter clean
flutter pub get

그리고 iOS 폴더에서 다시 Pods를 깔아봅니다.

cd ios
pod install
cd ..

5) Apple Silicon(M1/M2) + 시뮬레이터 아키텍처 이슈

특정 Pod가 시뮬레이터용 아키텍처(특히 arm64)를 제대로 지원하지 않으면, 모듈이 빌드되지 못해 결과적으로 No such module 로 이어질 수 있습니다.

증상 힌트

  • 디바이스 빌드는 되는데 시뮬레이터만 실패
  • Xcode 로그에 building for iOS Simulator, but linking in object file built for iOS 같은 문구가 섞여 있음

해결 방향

  • 문제 Pod가 시뮬레이터 arm64 를 지원하는 최신 버전인지 확인
  • 임시로 시뮬레이터에서 arm64 제외(권장: 최소한으로, 임시 대응)

Podfile 의 post_install 에서 아래처럼 설정하는 방식이 흔합니다.

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      # 시뮬레이터 arm64 제외(임시 대응)
      config.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = 'arm64'
    end
  end
end

이 설정은 “모든 Pod 타겟”에 영향을 주므로, 근본 원인은 Pod 업데이트로 해결하는 것을 우선 추천합니다.

6) Xcode Build Settings에서 Framework Search Paths 와 SWIFT_INCLUDE_PATHS 확인

드물지만, 팀에서 iOS 프로젝트 설정을 커스텀하다가 Search Paths가 깨지면 모듈 탐색이 실패합니다.

Xcode에서 Runner 타겟을 선택하고 아래를 확인합니다.

  • Framework Search Paths 에 $(inherited) 가 있는지
  • Other Linker Flags 에 $(inherited) 가 있는지

$(inherited) 가 빠지면 CocoaPods가 주입하는 설정이 적용되지 않아 No such module 로 이어질 수 있습니다.

7) CI에서만 실패한다면: Pod 캐시/DerivedData 캐시 전략 점검

CI는 로컬과 달리 캐시를 공격적으로 재사용합니다. 그 결과 “이전 빌드의 Pods/모듈 캐시”를 잘못 물고 No such module 이 간헐적으로 납니다.

권장 체크리스트

  • Podfile.lock 이 바뀌면 Pods 캐시 키도 바뀌도록 설정
  • Xcode DerivedData를 캐시한다면, Xcode 버전/SDK 버전까지 키에 포함
  • 문제가 지속되면 DerivedData 캐시를 과감히 끄고 안정화 후 재도입

캐시 충돌로 간헐 실패가 나는 전형적인 패턴과 해결 방식은 GitHub Actions 캐시 충돌로 CI 간헐 실패 디버깅 글을 참고하면 원인 추적이 빨라집니다.

8) 10분 플로우(요약)

아래 순서대로 하면 대부분 10분 안에 끝납니다.

  1. Xcode를 ios/Runner.xcworkspace 로 열기
  2. flutter clean 후 Pods 재설치
  3. DerivedData 삭제
  4. Podfile 의 use_frameworks! / use_modular_headers! 불필요 설정 제거 또는 문서 기반 최소 적용
  5. Apple Silicon 시뮬레이터 아키텍처 이슈면 EXCLUDED_ARCHS 임시 적용
  6. CI면 캐시 키/전략 재설계

부록) 문제 재현/진단에 유용한 명령어

CocoaPods 상태 확인

cd ios
pod --version
pod install --repo-update --verbose

Flutter iOS 빌드 로그를 더 자세히

flutter build ios -v

Xcode에서 어떤 설정으로 빌드되는지 확인

cd ios
xcodebuild -workspace Runner.xcworkspace -scheme Runner -configuration Debug -showBuildSettings

위 출력에서 $(inherited) 누락, Search Paths 이상, 특정 Pod 타겟의 빌드 설정이 튀는 지점을 찾으면 “왜 모듈이 안 만들어졌는지”가 드러납니다.

마무리

No such module 은 결과 메시지일 뿐이고, 원인은 대개 Pods 통합 실패, 캐시 꼬임, 빌드 설정 상속 누락, 아키텍처 미지원 중 하나입니다. 가장 성공률이 높은 해결책은 “워크스페이스 확인 후 Pods/DerivedData를 깨끗이 재생성”이고, 그 다음이 Podfile 설정과 아키텍처 점검입니다.

그래도 해결이 안 된다면, 에러가 난 모듈명과 함께 flutter build ios -v 로그에서 해당 모듈의 “컴파일 단계가 실제로 수행됐는지”를 먼저 확인하세요. 모듈이 빌드조차 안 됐다면 설정/Pods 문제이고, 빌드는 됐는데 임포트가 실패한다면 Search Paths나 use_frameworks! 계열 충돌일 가능성이 큽니다.

Discuss on Twitter • View on GitHub