Flutter 3.47 iOS 빌드 실패: 2026 어떻게 해결할까?

2026년 9월 14일 Xcode 27이 정식 출시됐습니다. 애플의 Xcode 출시 자료와 Flutter 공식 변경 기록을 함께 보면, Flutter 3.47 계열의 SwiftPM 관련 iOS 빌드 오류와 Xcode 27에서 Add-to-App 프로젝트가 Flutter Swift 패키지를 빌드하지 못하는 문제가 3.47.2 수정 항목에 포함되어 있습니다.

증상 → 가장 빠른 해결: Flutter 3.47의 최신 안정 패치로 먼저 올리고, 같은 커밋으로 의존성 해석과 Archive를 다시 실행합니다.
그래도 실패 → 다음 분기: 프로젝트 유형별 SwiftPM 통합과 플러그인 지원 여부를 확인하고, 호환되지 않는 플러그인이 있을 때만 CocoaPods를 임시 경로로 남깁니다.

마지막 업데이트: 2026년 9월 16일. Flutter 안정 채널의 공식 변경 기록, 애플의 Xcode 27 자료, Flutter SwiftPM 문서를 기준으로 확인했습니다.

이 글은 Flutter 3.47로 올린 뒤 기존 iOS 프로젝트가 빌드 또는 Archive에서 멈춘 독립 개발자를 위한 문서입니다. Xcode 27과 원격 맥에서 무인 빌드를 운영하는 담당자, SwiftPM과 CocoaPods 플러그인을 함께 사용하는 소규모 팀도 대상입니다.

첫 단계: 실패한 환경을 먼저 보존합니다

같은 커밋이 이전 환경에서는 성공했지만 Flutter 3.47과 Xcode 27로 바꾼 뒤 실패했다면, 바로 캐시를 삭제하지 마십시오. 마지막 줄의 오류만 복사하면 실제 원인을 잃기 쉽습니다.

먼저 다음 정보를 한 번에 저장합니다.

• 실제 Flutter 패치 버전과 안정 채널 상태
• Xcode 버전과 선택된 개발자 도구 경로
• 실행한 명령과 작업 디렉터리
• 첫 번째 유효한 오류 메시지
• pubspec.lock, Package.resolved, Podfile.lock 상태
• 의존성 해석, 일반 Build, Release Archive의 결과
• 그래픽 세션과 SSH 또는 CI에서 각각 실행한 결과

프로젝트명, 저장소 주소, 번들 식별자, 팀 식별자, 계정, 호스트 주소와 파일 경로는 기록을 공유하기 전에 가립니다. 로그의 마지막에 나타난 서명 오류가 실제로는 앞선 패키지 생성 실패의 결과일 수 있기 때문입니다.

Flutter 3.47로 올린 뒤 iOS 프로젝트가 빌드되지 않는 이유는 무엇입니까?
모든 오류가 하나의 Flutter 회귀로 설명되지는 않습니다. Flutter 패치 버전, Xcode 27 전환, SwiftPM 통합 상태, 플러그인 의존성, 원격 실행 권한이 서로 다른 지점에서 실패할 수 있습니다. 먼저 업그레이드 직후의 첫 오류를 이전 성공 로그와 비교해야 합니다.

두 번째 단계: Flutter 패치와 Xcode 기준선을 맞춥니다

Flutter 공식 변경 기록에는 SwiftPM을 켠 iOS 및 macOS 빌드 실패, 원래 iOS 프로젝트에 통합하는 Add-to-App 프로젝트의 Xcode 27 빌드 실패가 Flutter 3.47.2 수정 항목으로 기록되어 있습니다. 이후 기록에는 3.47.3도 이어서 표시됩니다. 따라서 3.47.0과 3.47.1을 사용하면서 SwiftPM 자체를 먼저 의심하는 것은 순서가 맞지 않습니다. Flutter 공식 변경 기록에서 현재 안정 패치의 항목을 확인하십시오.

확인 대상	먼저 할 일	실패할 때의 판단
Flutter	최신 3.47 안정 패치로 별도 브랜치에서 재현	패치 전후 오류가 달라지는지 확인
Xcode	Xcode 27과 선택된 개발자 도구 경로 확인	다른 Xcode를 보고 있는지 점검
소스	같은 커밋과 같은 잠금 파일 사용	코드 변경과 환경 변경을 분리
명령	기존 Build 명령을 그대로 사용	명령 변경으로 생긴 오류를 배제
결과	의존성 해석 후 Build와 Archive를 각각 기록	성공 단계를 섞지 않음

패치 업그레이드의 목적은 프로젝트를 새 구조로 재작성하는 것이 아닙니다. 기존 소스와 플러그인 잠금 상태를 유지한 채, Flutter 패치만 바꿔 회귀가 해소되는지 확인하는 것입니다.

주의: flutter clean, Package Cache 초기화, Pod 설정 삭제는 첫 조치가 아닙니다. 이 작업은 재현 단서를 없애고, 다시 내려갈 때 필요한 상태까지 지울 수 있습니다. 먼저 로그와 잠금 파일을 보존하고, 되돌릴 기준을 정하십시오.

Xcode 27에서 Flutter Swift Package 빌드가 계속 실패하면 어떻게 합니까?
Flutter 버전이 수정 항목을 포함하는지 확인한 다음 프로젝트 유형을 나눠야 합니다. 일반 Flutter 앱, 원래 iOS 프로젝트에 붙인 Add-to-App, 사용자 정의 Target은 SwiftPM 연결 증거가 서로 다릅니다. Flutter Add-to-App 문서와 SwiftPM 통합 문서를 기준으로 현재 구조를 확인하십시오.

세 번째 단계: SwiftPM 통합을 프로젝트 유형별로 재검증합니다

FlutterGeneratedPluginSwiftPackage가 필요한 구조인지 확인합니다. Xcode 프로젝트 또는 워크스페이스에 해당 패키지가 연결되어 있는지, 빌드 전 단계 스크립트가 실행되는지, 올바른 Target이 패키지에 의존하는지 순서대로 봅니다.

다음 세 가지를 섞으면 안 됩니다.

• 일반 Flutter 앱: Flutter가 생성한 iOS 호스트 프로젝트와 플러그인 연결을 확인합니다.
• Add-to-App: 기존 네이티브 iOS 프로젝트의 Target과 Flutter 모듈 연결을 확인합니다.
• 사용자 정의 Target: 앱 Target 외에 테스트, 확장 기능 또는 별도 패키징 Target이 같은 의존성을 요구하는지 확인합니다.

SwiftPM의 패키지 해석이 성공했어도 Xcode Build가 성공한다는 뜻은 아닙니다. 반대로 Xcode에서 패키지가 보인다고 해서 Archive에 필요한 Target 의존성이 완성된 것도 아닙니다. Swift Package Manager 공식 저장소의 동작 범위와 Flutter 문서의 연결 방식을 나눠서 확인해야 합니다.

Flutter SwiftPM 빌드 실패를 CocoaPods로 되돌려야 합니까?
플러그인이 SwiftPM을 지원하지 않는다는 증거가 있을 때만 CocoaPods를 임시 회귀 경로로 사용합니다. 먼저 모든 설정을 삭제하고 되돌리는 방식은 권하지 않습니다. 호환 플러그인까지 제거하면 원래 작동하던 의존성 경로를 잃을 수 있습니다.

네 번째 단계: 플러그인과 이중 의존성 경로를 분리합니다

각 플러그인을 다음 기준으로 확인하십시오.

• 현재 버전이 SwiftPM 통합을 지원하는지
• 네이티브 iOS 의존성이 별도 저장소 인증을 요구하는지
• 수동으로 수정한 Podfile이 남아 있는지
• 최소 지원 운영 체제 조건이 바뀌었는지
• Flutter가 호환되지 않는 플러그인 때문에 CocoaPods로 되돌아갔는지
• 같은 라이브러리가 SwiftPM과 CocoaPods 양쪽에서 중복 연결되는지

증거	선택할 경로	되돌림 조건
모든 플러그인이 SwiftPM 지원	SwiftPM 유지	패치 버전과 Target 연결 재검증
일부 플러그인만 미지원	CocoaPods 임시 유지	플러그인 업데이트 뒤 다시 SwiftPM 검토
Podfile 수동 설정이 핵심	현재 설정을 별도 브랜치에 보존	새 설정이 Archive까지 통과할 때만 교체
패키지 해석은 성공하지만 Build 실패	Target과 스크립트 점검	캐시 삭제보다 연결 상태를 우선 확인
의존성 자체가 인증에서 실패	저장소 권한과 자격 증명 점검	권한 복구 후 같은 잠금 파일로 재시도

Pod 설정을 지우기 전에는 변경 범위를 기록합니다. Podfile, 잠금 파일, 사용자 정의 빌드 설정, 비공개 네이티브 의존성을 한꺼번에 없애면 실패 원인을 복원하기 어려워집니다. CocoaPods를 사용해야 한다면 “최종 선택”이 아니라 호환성 확인을 위한 취소 가능한 임시 경로로 운영하십시오.

다섯 번째 단계: 일반 Build와 Archive를 따로 승인합니다

Debug Build 성공은 출시 준비가 끝났다는 증거가 아닙니다. 최소한 아래 순서로 통과 여부를 따로 기록합니다.

1. 패키지와 플러그인 의존성 해석
2. Debug 또는 개발용 일반 Build
3. Release Build
4. Archive 생성
5. 내보내기와 필요한 서명 단계
6. 테스트 업로드 또는 실제 배포 직전 검증

수정 후 Flutter iOS Archive가 출시 가능한지 어떻게 확인합니까?
Archive 파일이 만들어졌다는 사실만으로 충분하지 않습니다. Release 설정으로 Archive하고, 내보내기 단계에서 필요한 서명 자산과 프로비저닝 설정이 선택되는지 확인해야 합니다. 업로드 전 검증까지 같은 커밋으로 끝내야 “빌드 복구”와 “출시 체인 복구”를 구분할 수 있습니다.

이 글의 초점은 인증서나 키체인 자체의 장애가 아닙니다. Archive가 의존성 또는 Xcode Build 단계에서 실패한다면 먼저 이 문서의 순서를 따르십시오. Archive가 성공한 뒤 서명에서만 멈출 때는 Flutter iOS 서명과 키체인 점검 환경처럼 별도 점검 경로로 분리하는 편이 안전합니다.

여섯 번째 단계: 원격 맥에서는 환경 문제를 따로 격리합니다

내 컴퓨터에서는 패키징되는데 원격 맥에서만 실패하면 무엇부터 봐야 합니까?
같은 커밋으로 로컬과 원격 맥의 Flutter, Xcode, 개발자 도구 경로, 작업 디렉터리, 권한, 자격 증명 세션, 의존성 캐시 소유자를 비교하십시오. 원격 작업만 실패한다면 프로젝트 회귀로 단정하지 말고 실행 환경부터 분리합니다.

원격 맥에서 확인할 항목은 다음과 같습니다.

• SSH와 그래픽 세션이 같은 개발자 도구를 선택하는지
• 저장소와 빌드 디렉터리에 실행 계정의 읽기·쓰기 권한이 있는지
• 패키지 캐시가 다른 계정 소유로 남아 있지 않은지
• 비공개 의존성에 필요한 인증 세션이 자동 실행에서도 유효한지
• GUI에서 성공한 값이 CI 환경 변수에 전달되는지
• 호스트 재시작 뒤에도 Flutter와 Xcode 경로가 유지되는지

원격 맥을 새로 만들기 전에, 현재 환경에서 실패를 재현할 수 있는 최소 프로젝트를 준비하십시오. 그래픽 세션에서 성공하고 SSH에서만 실패한다면 도구 체인 선택이나 권한 문제일 가능성이 높습니다. 반대로 두 세션에서 같은 패키지 해석 오류가 난다면 프로젝트 의존성부터 다시 봐야 합니다.

현재 별도 장비를 구매하지 않고 원격 맥을 시험해야 한다면 원격 맥 기반 iOS 빌드 환경을 검토할 수 있습니다. 다만 먼저 프로젝트의 Build와 Archive 명령을 고정하고, 환경을 바꾼 뒤에는 같은 커밋으로 비교해야 합니다.

일곱 번째 단계: 첫 성공을 장기 운영 기준으로 고정합니다

첫 성공 뒤에도 다음 변경을 모두 한 번에 진행하지 마십시오.

• Flutter 패치 변경
• Xcode 소버전 변경
• 플러그인 업데이트
• 잠금 파일 재생성
• CocoaPods와 SwiftPM 경로 전환
• 생산용 원격 맥 교체

첫 주에는 최소 회귀 작업을 남깁니다. 의존성 해석, 일반 Build, Release Archive, 내보내기, 업로드 전 검증을 같은 순서로 실행합니다. 이후 연결을 끊었다가 다시 접속하고, 호스트를 재시작한 뒤 같은 작업을 반복합니다.

• [ ] Flutter 안정 패치 버전을 고정했습니다.
• [ ] Xcode 버전과 개발자 도구 경로를 기록했습니다.
• [ ] 소스와 의존성 잠금 파일을 보존했습니다.
• [ ] SwiftPM 통합 대상과 Target 의존성을 확인했습니다.
• [ ] SwiftPM 미지원 플러그인만 별도로 분리했습니다.
• [ ] CocoaPods 회귀 경로와 복구 조건을 문서화했습니다.
• [ ] Debug Build와 Release Archive를 따로 통과시켰습니다.
• [ ] 내보내기와 업로드 전 검증을 완료했습니다.
• [ ] SSH 또는 CI 실행 결과를 그래픽 세션과 비교했습니다.
• [ ] 연결 해제와 호스트 재시작 뒤 다시 검증했습니다.

Windows나 리눅스 개발 컴퓨터만으로는 Xcode 27의 전체 Archive와 출시 검증을 독립적으로 끝내기 어렵습니다. 기존 원격 환경이 자주 초기화되면 Flutter와 Xcode를 이중으로 유지하기도 힘들고, CocoaPods와 SwiftPM 잠금 상태가 매번 달라질 수 있습니다.

이 경우 장기 장비를 바로 구매하기보다, 먼저 원격 맥에서 실제 출시 작업을 재현해 보는 편이 합리적입니다. MACCOME의 맥 미니 원격 환경을 사용한다면 임시로 패치 전후 환경을 나누고, Archive와 재시작 복구까지 확인한 뒤 계속 보유할지 결정하십시오. 반대로 장기간 같은 프로젝트를 무거운 작업으로 운영하거나 물리 장비와 주변 기기가 필요하다면 직접 장비를 관리하는 편이 더 적합할 수 있습니다.