Flutter 공식 자료는 Flutter 3.44부터 iOS와 macOS 의존성 관리의 기본 방식으로 Swift Package Manager를 안내합니다. 따라서 Flutter 3.47 프로젝트도 전부 자동 전환됐다고 가정하지 말고, 플러그인별 의존성 경로를 확인한 뒤 깨끗한 Mac CI에서 복원·빌드·아카이브를 차례로 검수해야 합니다. Flutter SwiftPM 통합 안내와 안정 버전 릴리스 안내를 기준으로 프로젝트 설정을 대조하세요.
Flutter iOS 앱 유지보수 담당자: 3.47 업그레이드 전에 기존 플러그인과 네이티브 의존성을 확인해야 합니다.
CI 엔지니어: Mac 빌드 노드에서 SwiftPM 복원, 아카이브와 서명을 확인해야 합니다.
Flutter 플러그인 관리자: SwiftPM 지원 여부와 CocoaPods 대체 경로를 판단해야 합니다.
마지막 검토: 2026년 10월 31일. Flutter 공식 안정 버전·SwiftPM·플러그인 안내와 Apple의 CI 문서를 확인했습니다.
Flutter 3.47 iOS CI SwiftPM 검수는 프로젝트 유형부터 나눕니다
Flutter 3.47이라는 버전만으로 현재 프로젝트의 의존성 관리 상태를 알 수는 없습니다. Flutter의 기본값에 관한 설명은 출발점이지, 이미 구성된 앱과 플러그인의 설정 변경 내역을 대신 확인해 주는 것은 아닙니다. Flutter의 SwiftPM 앱 개발자 문서에서 안내하는 설정과 실제 저장소를 대조하고, 팀이 직접 변경한 항목은 커밋 기록으로 구분하세요.
| 프로젝트 상황 | 먼저 확인할 항목 | 통과 판단 기준 |
|---|---|---|
| Flutter iOS 앱과 SwiftPM 지원 플러그인 | 플러그인 선언, 패키지 해석 결과, 잠금 상태 | 깨끗한 작업 공간에서 동일한 의존성을 복원하고 빌드합니다 |
| SwiftPM 미지원 플러그인 포함 | 플러그인 문서와 Flutter CLI 로그 | CocoaPods 대체 경로가 실행됐는지 기록하고 실제 빌드까지 확인합니다 |
| 기존 iOS 앱에 Flutter 모듈 삽입 | 호스트 Xcode 프로젝트, 통합 방식, 빌드 진입점 | 호스트 앱의 패키지 해석과 아카이브를 따로 확인합니다 |
여기서 주의할 점은 로컬 Mac의 성공이 저장소의 재현 가능성을 보장하지 않는다는 것입니다. 개발자 환경의 캐시나 기존 생성 파일이 빠진 의존성을 가리고 있을 수 있습니다. 이는 문서에 적힌 자동 보장 사항이 아니라, 깨끗한 환경을 따로 두어야 하는 실무상 판단입니다.
일반 Flutter 앱에서는 플러그인 선언과 잠금 상태를 대조합니다
Flutter 플러그인 개발 문서와 각 플러그인의 지원 정보를 확인해 SwiftPM 경로를 기대할 수 있는지 살펴보세요. 패키지 이름만 보고 호환 여부를 판단하지 말고, iOS 구현과 네이티브 의존성 선언을 확인해야 합니다. 특히 팀에서 플러그인 버전을 바꾸었거나 설정을 수동 수정했다면, Flutter가 생성하는 파일과 저장소에 넣은 파일을 구분해 기록하세요.
그다음 CI에서 저장소를 새로 가져와 의존성을 해석합니다. 개발자 Mac에만 남아 있는 패키지 캐시를 사용하지 않도록 작업 공간을 초기화하고, 잠금 파일의 변경 여부도 확인합니다. 같은 커밋으로 다시 실행했을 때 패키지 해석 결과가 달라진다면, 아카이브 검수에 앞서 원인을 해결해야 합니다.
주의: 잠금 파일이 있다고 해서 비공개 패키지 접근 권한까지 재현되는 것은 아닙니다. 인증이 필요한 저장소는 CI 자격 증명 설정을 별도로 확인하고, 로그에 비밀 값이 출력되지 않도록 처리하세요.
SwiftPM 미지원 플러그인은 CocoaPods 대체 경로를 로그로 확인합니다
Flutter 문서는 SwiftPM을 지원하지 않는 플러그인의 CocoaPods 대체 경로를 안내합니다. 플러그인 작성자를 위한 SwiftPM 이전 문서도 함께 확인해 플러그인 작성자가 선언한 지원 방식과 프로젝트에서 실제 사용한 경로를 구분하세요. 대체 기능이 있다는 사실만으로 모든 CocoaPods 플러그인의 호환이 확인된 것은 아닙니다.
Flutter CLI 출력과 Xcode 빌드 로그에서 어떤 의존성이 어떤 경로로 들어왔는지 남깁니다. 대체 경로가 선택됐다면 그 상태로 복원, 테스트, 아카이브가 성공했는지 확인하세요. 이후 플러그인 업데이트나 설정 변경으로 경로가 달라질 수 있으므로, 팀의 CI 기록에는 사용한 커밋과 로그를 묶어 보관하는 편이 안전합니다.
| 확인 대상 | 통과하지 못했을 때 살펴볼 원인 | 기록할 증거 |
|---|---|---|
| SwiftPM 플러그인 선언과 패키지 해석 | 플러그인 버전, 저장소 접근, 잠금 파일 변경 | 해석 로그와 변경된 파일 |
| CocoaPods 대체 처리 | 플러그인 지원 범위, CLI 경고, 기존 Pod 설정 | 실제 대체 경로가 보이는 로그 |
| CI 재실행 결과 | 캐시 의존, 인증 설정, 실행 환경 차이 | 같은 커밋의 재실행 기록 |
Flutter 공식 문서는 CocoaPods 저장소가 2026년 12월 2일 읽기 전용으로 전환될 예정이라고 안내합니다. 이 날짜는 검토 시점에 미래의 공식 일정이며, 이미 전환이 끝났다는 뜻은 아닙니다. 따라서 현재의 대체 경로 동작과 향후 저장소 운영 계획을 구별해 관리하세요. Flutter SwiftPM 안내에서 최신 문서 내용도 다시 확인해야 합니다.
기존 iOS 호스트 앱에 Flutter를 넣었다면 별도로 검수합니다
Flutter 모듈을 기존 iOS 앱에 통합한 프로젝트는 일반 Flutter 앱과 같은 방식으로만 판단할 수 없습니다. 호스트 Xcode 프로젝트의 패키지 설정과 빌드 진입점이 앱의 의존성 결과에 영향을 주기 때문입니다. 기존 iOS 프로젝트에 Flutter를 통합하는 공식 안내를 기준으로 현재 통합 방식을 확인하고, 기존 CocoaPods 구성을 정리했다면 정리 대상이 맞는지도 별도로 검토하세요.
첫째, 호스트 앱과 Flutter 모듈의 저장소 및 빌드 진입점을 확인합니다.
둘째, CI 작업 공간을 새로 만들고 해당 커밋을 가져옵니다.
셋째, 필요한 패키지와 비공개 Git 의존성을 해석하고 로그를 보관합니다.
넷째, 의존성 복원 뒤 테스트와 Xcode 빌드를 실행합니다.
다섯째, 배포용 아카이브를 만들고 서명 및 산출물 정보를 점검합니다.
여섯째, 같은 커밋으로 다시 실행해 캐시나 로컬 설정에 기대지 않는지 확인합니다.
이는 팀이 재현 가능한 결과를 얻기 위한 검수 절차입니다. 자동 마이그레이션이 모든 사용자 설정을 정리해 준다고 가정하지 말고, 수동 변경과 공식 이전 절차를 구분해야 합니다.
Mac CI에서 복원부터 IPA 서명까지 확인합니다
Apple은 CI에서 Swift 패키지를 사용하는 앱을 빌드할 때 필요한 인증과 Git 도구 설정을 안내합니다. Apple의 Swift 패키지 CI 문서를 참고해 비공개 의존성의 접근 방식을 점검하세요. 비밀 값은 로그에 그대로 남기지 말고, 접근 권한과 출력 마스킹을 확인해야 합니다.
| 검수 단계 | 통과 조건 | 남길 증거 |
|---|---|---|
| 의존성 복원 | 깨끗한 작업 공간에서 패키지 해석이 완료됩니다 | 해석 로그, 잠금 파일 상태 |
| 테스트와 빌드 | 지정한 커밋에서 테스트와 Xcode 빌드가 완료됩니다 | 작업 결과와 빌드 로그 |
| 아카이브와 서명 | 배포용 산출물과 서명 정보가 확인됩니다 | 아카이브 로그, 서명 및 산출물 정보 |
Flutter iOS 배포 안내에 따라 배포 대상과 빌드 조건도 확인하세요. 의존성 복원 성공만으로 IPA 검수를 끝내지 말고, 실제 배포 흐름에서 요구되는 아카이브와 서명 결과까지 남겨야 합니다.
결과에 따라 전환 범위를 결정합니다
아래 조건 분기로 전체 전환, 필요한 대체 경로 유지, 또는 보류 중 하나를 고르세요.
- 플러그인이 SwiftPM을 지원하고, 깨끗한 Mac CI에서 복원·테스트·아카이브가 모두 성공하면 해당 프로젝트의 전환을 진행합니다.
- 지원되지 않는 플러그인이 있지만 CocoaPods 대체 경로로 동일한 검수를 통과하면 확인된 범위에서만 대체 경로를 유지하고 의존성별 로그를 보관합니다.
- 캐시를 비운 환경에서 복원이 실패하거나 서명 산출물을 확인하지 못하면 전환 범위를 넓히지 말고 원인을 해결한 뒤 다시 검수합니다.
- 기존 iOS 호스트 앱의 통합 방식이 불명확하면 일반 Flutter 앱과 분리해 호스트 프로젝트부터 재검토합니다.
참고: CocoaPods 저장소의 읽기 전용 전환은 공식 안내에 기재된 예정 사항입니다. 이미 적용된 상태로 취급하지 말고, 실제 전환 여부와 날짜는 작업을 진행할 때 공식 문서에서 다시 확인하세요.
이 기준을 저장소별로 적용하면 “Flutter 3.47로 올렸으니 모두 SwiftPM”이라는 일괄 결정을 피할 수 있습니다. 팀에서 이미 쓰는 Mac 빌드 환경이 있다면 대표 프로젝트의 결과를 먼저 기록한 뒤, 같은 검수 기준을 다른 앱과 플러그인에 적용하세요.
자주 묻는 항목
독립형 Mac이 없는 팀은 로컬 개발 장비에서만 결과를 확인하기보다 깨끗한 Mac CI 작업 공간에서 동일한 커밋을 검수해야 합니다. 이미 Mac 실행 환경이 있다면 새 장비나 원격 노드를 추가하기 전에 이 절차를 먼저 실행하세요.
전환 전에 SwiftPM과 CocoaPods 양쪽을 모두 제거해야 하나요?
아닙니다. 실제 플러그인이 사용하는 경로를 확인하기 전에는 기존 설정을 일괄 삭제하지 마세요. Flutter 문서와 플러그인 지원 정보를 대조하고, CLI와 빌드 로그에서 실제 선택된 경로를 확인한 다음 불필요한 설정만 정리해야 합니다.
Mac CI 환경이 없다면 대표 프로젝트부터 원격으로 검수합니다
기존 방식이 개발자 Mac 한 대에 의존하면 작업 공간의 캐시가 누락 의존성을 가릴 수 있고, 재검수 환경을 팀원이 공유하기 어렵고, 아카이브와 서명 증거도 개인 장비에 흩어질 수 있습니다. 반면 장기간 고정된 부하를 계속 처리하거나 물리 장비 연결이 필요한 팀에는 자체 Mac을 마련하는 편이 맞을 수 있습니다.
현재 환경을 유지할지 원격 Mac을 쓸지는 비용만이 아니라 재현성과 접근 조건으로 결정하세요. 우선 대표 Flutter 프로젝트 하나에서 의존성 복원, 테스트, 아카이브와 서명을 끝까지 실행하고, 결과를 저장소의 커밋 및 로그와 연결해 두는 것이 좋습니다. 필요한 기간 동안 Mac CI 노드를 확보해야 한다면 RUVCLOUD 요금 안내에서 이용 조건을 확인하고, Mac 환경 주문 안내를 살펴볼 수 있습니다. 이는 자체 장비를 대체해야 한다는 뜻이 아니라, 전환 검수에 쓸 재현 가능한 Mac 환경이 없는 팀을 위한 선택지입니다.