beautifulsoups.dev
Published on

Flutter iOS 빌드 No such module Flutter 해결

Authors

Flutter로 iOS 빌드를 하다 보면 Xcode 또는 flutter build ios 단계에서 No such module Flutter가 튀어나오는 경우가 있습니다. 겉으로는 모듈을 못 찾는 단순 오류처럼 보이지만, 실제로는 CocoaPods 통합 상태, 생성된 iOS 아티팩트(특히 Flutter.framework/Flutter.podspec/xcconfig) 불일치, 빌드 캐시 손상, 워크스페이스 열기 실수 등이 겹쳐서 발생하는 경우가 많습니다.

이 글에서는 가장 흔한 원인부터 “확실하게” 고치는 복구 순서를 제시하고, 팀/CI 환경에서 재발을 줄이는 방법까지 다룹니다.

오류가 의미하는 것

No such module Flutter는 Swift/ObjC 컴파일 단계에서 import Flutter(또는 Flutter 관련 헤더/모듈맵)를 해석하지 못할 때 발생합니다. 보통 아래 중 하나입니다.

  • Pods가 제대로 설치되지 않아 Flutter Pod가 모듈로 노출되지 않음
  • .xcworkspace가 아닌 .xcodeproj를 열어 Pods 설정이 로드되지 않음
  • Podfile.lock/Pods 캐시/DerivedData가 꼬여서 모듈맵이 깨짐
  • ios/Flutter/Generated.xcconfig 등 Flutter가 생성하는 설정 파일이 유실되었거나 오래됨
  • Apple Silicon 환경에서 Ruby/CocoaPods/ffi 문제로 설치가 부분 실패
  • Xcode 버전/SDK 업데이트로 빌드 시스템이 이전 캐시를 잘못 참조

가장 먼저 확인할 3가지 (5분 컷)

1) .xcworkspace로 열었는지 확인

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

  • 잘못된 예: ios/Runner.xcodeproj
  • 올바른 예: ios/Runner.xcworkspace

터미널에서 아래로 열면 실수가 줄어듭니다.

open ios/Runner.xcworkspace

2) flutter clean 이후 재생성

Flutter 생성물(특히 iOS 관련 설정)이 꼬였을 때 가장 빠른 리셋입니다.

flutter clean
flutter pub get

3) Pods 재설치

ios 디렉터리에서 Pods를 완전히 지우고 다시 설치합니다.

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

여기까지 했는데도 동일하면, 아래 “확실한 복구 루틴”으로 넘어가세요.

확실한 복구 루틴 (원인 불명일 때 가장 잘 먹힘)

아래 순서는 “문제 원인이 여러 개 겹쳐도” 함께 정리되도록 구성했습니다.

1) Xcode 완전 종료

Xcode가 열려 있으면 DerivedData/인덱싱/빌드 캐시가 계속 잡혀서 삭제가 덜 되는 경우가 있습니다.

2) DerivedData 삭제

rm -rf ~/Library/Developer/Xcode/DerivedData

3) Flutter 캐시 정리 및 iOS 아티팩트 재생성

flutter clean
flutter pub get

4) Pods 완전 재설치 + repo update

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

5) 다시 빌드

flutter build ios --debug

디버그가 통과하면 릴리즈도 확인합니다.

flutter build ios --release

원인별로 더 깊게: 자주 놓치는 포인트

1) Generated.xcconfig/Flutter 설정 파일 누락

ios/Flutter/Generated.xcconfig는 flutter pub get 또는 Xcode 빌드 과정에서 생성/갱신됩니다. 파일이 없거나 오래되면 Pods가 참조하는 설정이 틀어질 수 있습니다.

확인 포인트:

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

재생성은 보통 아래로 해결됩니다.

flutter pub get
cd ios
pod install
cd ..

2) Pod 설치는 됐는데 모듈이 안 보이는 경우 (모듈맵/빌드 설정)

Swift 프로젝트에서 import Flutter가 실패한다면, Pods가 Runner 타깃에 제대로 링크되지 않았거나, 워크스페이스 로딩이 안 되었거나, Framework Search Paths가 꼬였을 수 있습니다.

가장 흔한 실수는 역시 .xcodeproj를 열어 빌드하는 것입니다. CI에서도 xcodebuild를 워크스페이스로 돌리는지 확인하세요.

예시:

xcodebuild \
  -workspace ios/Runner.xcworkspace \
  -scheme Runner \
  -configuration Debug \
  -sdk iphonesimulator \
  build

3) Apple Silicon에서 CocoaPods/ffi 이슈로 설치가 반쯤 실패

M1/M2 환경에서 Ruby 네이티브 확장(특히 ffi) 문제로 pod install이 실패하거나 경고만 남기고 일부가 깨질 수 있습니다.

증상:

  • pod install 로그에 ffi 관련 에러가 있었는데 대충 넘어감
  • 이후 Xcode에서 No such module Flutter가 발생

대응:

  • CocoaPods를 정상 설치/업데이트
  • Ruby 환경을 통일(rbenv, asdf 등)

예시(환경에 따라 조정 필요):

sudo gem install cocoapods
pod --version

만약 팀 내에서 머신마다 Ruby가 다르면, CI와 로컬이 서로 다른 결과를 만들 수 있습니다. 이 경우에는 Ruby 버전 고정(예: .ruby-version)과 CocoaPods 버전 고정이 장기적으로 효과가 큽니다.

4) iOS Deployment Target 불일치

Pods가 요구하는 최소 iOS 버전과 Runner의 타깃이 다르면 설치는 되더라도 빌드 단계에서 이상한 형태로 터질 수 있습니다.

ios/Podfile에서 최소 버전을 올려 정렬합니다.

platform :ios, '13.0'

# ...
post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '13.0'
    end
  end
end

설정 변경 후에는 Pods를 다시 설치하세요.

cd ios
pod install
cd ..

5) 워크스페이스는 맞는데, 특정 타깃에서만 터지는 경우 (Extension, Notification Service 등)

앱 확장 타깃(예: Share Extension, Notification Service Extension)을 추가한 뒤, 해당 타깃에서 import Flutter를 시도하면 실패할 수 있습니다. Flutter 엔진/프레임워크를 확장 타깃에 링크하는 것은 일반적인 구성과 다르기 때문입니다.

대응 전략:

  • 확장 타깃에서는 Flutter 의존을 제거하고, 앱과는 App Group/URL scheme 등으로 통신
  • 혹은 Flutter를 포함하는 구조를 별도 설계(권장 난이도 높음)

즉, “확장 타깃에서도 Flutter를 그냥 import”하는 접근은 대부분 막힙니다.

CI에서 재발 방지 체크리스트

로컬에서는 되는데 CI에서만 No such module Flutter가 나는 경우는 대개 캐시/경로/워크스페이스 설정 문제입니다.

  • flutter --version 고정(FVM 사용 권장)
  • pod install 전에 flutter pub get 실행
  • xcodebuild는 반드시 -workspace 사용
  • DerivedData 캐시를 쓸 경우 키를 Xcode 버전/Flutter 버전/Podfile.lock 해시까지 포함

빠르게 상태를 “진단”하는 관점은 쿠버네티스 장애 분석과도 유사합니다. 원인 후보를 넓게 잡고, 캐시/의존성/런타임 버전을 하나씩 고정해가며 재현성을 확보해야 합니다. 이런 접근이 익숙하지 않다면 Kubernetes CrashLoopBackOff 10가지 원인과 15분 진단처럼 “체크리스트로 빠르게 좁혀가는 방식”이 큰 도움이 됩니다.

자주 묻는 질문

Q) pod install은 성공인데 왜 계속 모듈을 못 찾나요?

성공 로그가 떠도 실제로는 워크스페이스를 열지 않았거나, DerivedData에 남은 오래된 모듈맵을 참조하거나, 타깃/스킴이 달라 Pods 링크가 적용되지 않는 경우가 많습니다. 이 글의 “확실한 복구 루틴”대로 DerivedData 삭제까지 포함해 정리해보세요.

Q) flutter build ios는 되는데 Xcode에서만 실패합니다.

대부분 Xcode에서 .xcodeproj를 열었거나, Xcode의 스킴/빌드 설정이 다른 구성을 보고 있는 상황입니다. Runner.xcworkspace를 열고, 스킴이 Runner인지 확인하세요.

결론: 가장 성공률 높은 해결 순서

  1. Runner.xcworkspace로 열기
  2. flutter clean + flutter pub get
  3. ios에서 Pods/Podfile.lock 삭제 후 pod install
  4. DerivedData 삭제
  5. 그래도 안 되면 iOS 타깃 버전 정렬, Apple Silicon Ruby/CocoaPods 환경 점검, 확장 타깃 import 여부 확인

No such module Flutter는 한 번 꼬이면 계속 재발하는 것처럼 보이지만, 실제로는 “빌드 입력(Flutter 버전, Pods, 설정 파일)과 캐시 상태가 불일치”해서 생기는 경우가 대부분입니다. 위 루틴으로 입력과 캐시를 다시 정렬하면 높은 확률로 복구됩니다.

Discuss on Twitter • View on GitHub