Flutter 공식 문서의 iOS 배포 절차는 macOS, Xcode, Apple 코드 서명 체인을 전제로 합니다. Flutter 3.44.0 공식 릴리스 문서를 기준으로 보면, Flutter 3.44 서명 실패는 인증서를 먼저 다시 만드는 문제가 아닙니다. 먼저 실패 단계를 나누고, 프로젝트 설정·서명 자산·타깃 권한·원격 키체인을 순서대로 확인해야 합니다. 그래픽 세션은 성공하지만 SSH만 실패한다면 비대화형 키체인 접근을 우선 고치십시오.

마지막 업데이트: 2026년 9월 7일. Flutter 3.44 릴리스 문서와 Flutter iOS 빌드 및 배포 문서, Apple의 서명 관련 문서를 기준으로 확인했습니다.

이 글은 Windows나 Linux에서 Flutter 앱을 작성하고 원격 맥으로 iOS 배포를 진행하는 독립 개발자를 위한 내용입니다. Flutter 3.44로 올린 뒤 Runner나 플러그인 타깃에서 서명이 깨진 기존 앱, SSH나 자동화 작업에서 flutter build ipa를 실행해야 하는 작은 팀도 대상입니다.

01

실패한 마지막 줄보다 첫 번째 유효 오류를 먼저 찾습니다

flutter build ios, 아카이브 생성, 아이파이 내보내기, 앱스토어 업로드는 서로 다른 단계입니다. 로그 마지막에 codesign이 표시되어도 최초 원인이 묶음 식별자 불일치인지, 프로파일 누락인지, 키체인 잠금인지 알 수 없습니다.

다음과 같이 로그를 탈취한 뒤 첫 번째 유효 오류를 찾으십시오.

flutter build ipa --release 2>&1 | tee /tmp/<project>-<date>-ipa.log

<project>, <date>는 실제 프로젝트명과 날짜를 노출하지 않는 내부 기록용 값으로 바꾸십시오. 로그에 실제 팀 식별자, 인증서 이름, 프로파일 식별자, 사용자명, 호스트 주소, 토큰이 들어갔다면 공유 전에 반드시 가리십시오.

먼저 다음 항목을 기록합니다.

  • 실행한 명령과 현재 커밋
  • 실제로 선택된 스킴과 빌드 설정
  • 실패한 타깃 이름
  • 실패한 단계
  • 첫 번째 유효 오류와 그 직전 명령
  • 그래픽 Xcode 세션과 SSH 세션의 결과 차이

Xcode에서 같은 커밋을 릴리스 아카이브로 만들어 보십시오. 그래픽 세션은 성공하고 SSH만 실패하면 프로젝트 전체를 다시 만드는 대신 환경 차이를 조사할 근거가 생깁니다. 반대로 두 경로 모두 같은 타깃에서 실패하면 Runner 설정이나 서명 자산부터 확인해야 합니다.

02

Flutter 3.44 서명 실패를 네 가지 원인으로 분리합니다

Runner의 팀과 묶음 식별자를 확인합니다

Xcode의 Runner 프로젝트, Runner 타깃, 릴리스 설정, 실제 스킴을 각각 확인하십시오. 팀이 올바른 계정으로 선택되어 있어도 다른 스킴이 사용되면 명령줄 빌드는 다른 설정을 읽을 수 있습니다.

개발자 계정의 앱 식별자와 프로젝트의 묶음 식별자도 정확히 비교해야 합니다. 대소문자나 접미사가 다른 앱 식별자는 별개의 대상입니다. 자동 서명과 수동 서명을 프로젝트, 타깃, 내보내기 단계에서 계획 없이 섞으면 개발 빌드는 되지만 릴리스 아카이브에서 실패할 수 있습니다.

통과 기준은 단순한 디버그 실행이 아닙니다. 동일한 커밋에서 릴리스 아카이브가 생성되고, 아카이브 안에 서명된 실제 앱 산출물이 있어야 합니다. Apple의 아카이브와 앱 배포 안내도 배포 작업을 아카이브와 내보내기 단계로 구분합니다.

인증서와 개인 키는 하나의 서명 신원으로 봅니다

인증서 파일만 가져왔다고 서명할 수 있는 것은 아닙니다. 다음 네 가지를 분리해서 보십시오.

  • 인증서 파일
  • 인증서에 대응하는 개인 키
  • 키체인에 표시되는 서명 신원
  • 현재 앱 식별자와 배포 유형에 맞는 프로비저닝 프로파일

Apple은 인증서를 유형별로 구분합니다. Apple 인증서 개요에서 현재 작업이 개발용인지 배포용인지 먼저 맞추십시오. 릴리스 작업에 개발 인증서만 연결하거나, 개인 키가 없는 배포 인증서를 가져오면 빌드 단계가 진행되어도 서명에서 중단될 수 있습니다.

프로비저닝 프로파일은 파일 하나가 아니라 앱 식별자, 배포 유형, 허용된 인증서와 기능을 묶은 서명 자료입니다. Apple의 프로비저닝 프로파일 기술 문서를 기준으로 현재 릴리스 타깃과 프로파일의 관계를 확인하십시오.

인증서 폐기, 프로파일 삭제, 키체인 초기화는 마지막 수단입니다. 실행하기 전에 기존 파일을 안전한 위치에 백업하고, 다른 빌드 머신과 진행 중인 배포에 미치는 영향을 기록하십시오. 새 자산을 만든 뒤에도 이전 머신이 더 이상 서명하지 못할 수 있으므로 즉시 삭제하지 말고 새 아카이브와 업로드를 먼저 확인해야 합니다.

플러그인과 확장 타깃은 별도로 검증합니다

Runner만 성공했다고 전체 앱이 정상인 것은 아닙니다. 알림 확장, 위젯, 공유 확장, 플러그인이 추가한 중첩 코드가 별도 타깃으로 들어가면 일부 타깃만 서명에 실패할 수 있습니다.

각 타깃에서 다음을 비교하십시오.

  • 타깃별 묶음 식별자
  • 팀 선택
  • 서명 방식
  • Signing & Capabilities 설정
  • 실제 프로비저닝 프로파일
  • 권한 선언 파일
  • 최종 아카이브 안의 앱과 확장 산출물

Runner와 플러그인 타깃은 같은 팀에 속할 수 있지만, 같은 프로파일을 무조건 사용하지는 않습니다. 타깃별 앱 식별자와 권한에 맞는 프로파일이어야 합니다. 알림이나 앱 그룹 같은 기능을 추가했다면 계정에서 해당 기능이 허용되었는지도 확인하십시오.

권한 선언은 소스 설정 화면만 보지 말고 최종 앱에서 확인해야 합니다. Apple entitlements 문서의 설명처럼 권한은 서명과 배포 결과에 연결됩니다. 아이파이가 생성되었더라도 검증 시 권한 불일치가 나타나면 내보낸 산출물과 프로파일을 다시 대조해야 합니다.

주의: 키체인 접근 제어를 넓게 열거나 모든 인증서를 자동화 작업에 노출하면 당장 빌드는 통과할 수 있습니다. 그러나 일반 작업이 배포용 개인 키를 사용할 수 있게 됩니다. 필요한 키와 작업 계정만 허용하고, 변경 전 설정과 되돌릴 명령을 별도로 기록하십시오.

03

원격 맥에서는 키체인과 세션 차이를 먼저 확인합니다

그래픽 Xcode에서 아카이브가 성공하지만 SSH에서 flutter build ipa가 실패한다면 프로젝트보다 세션 조건이 다를 가능성이 큽니다. 다만 이것은 모든 환경에 대한 일반 법칙이 아니라 현재 원격 맥에서 재현되는지 확인해야 하는 진단 가설입니다.

다음 세 경로를 같은 커밋에서 비교하십시오.

실행 경로 확인할 증거 다음 판단
그래픽 Xcode 세션 릴리스 아카이브, 타깃별 서명 결과 여기서도 실패하면 프로젝트 또는 자산 점검
SSH 터미널 기본 키체인, 잠금 상태, 서명 신원 인식 여기서만 실패하면 세션과 키체인 점검
자동화 작업 비대화형 접근, 재연결 뒤 상태, 로그 노출 여부 재실행 가능성과 최소 권한 확인

SSH 세션에서 현재 로그인한 사용자, 기본 키체인, 키체인 잠금 상태, 서명 신원이 그래픽 세션과 같은지 확인하십시오. 특정 명령을 무작정 복사하기보다 현재 키체인 이름과 서명 신원을 먼저 읽는 방식이 안전합니다. Apple의 코드 서명 관련 개발자 포럼 안내도 SSH 환경의 서명 문제에서 세션과 키체인 조건을 분리해 확인하도록 안내합니다.

원격 Mac을 지속적인 iOS 빌드 서버로 사용할 때는 다음 위험도 관리해야 합니다.

  • 세션이 끊긴 뒤 키체인이 다시 잠기는 문제
  • 재부팅 후 자동화 작업이 로그인 화면에서 멈추는 문제
  • 일반 빌드 작업에 개인 키가 노출되는 문제
  • 로그에 프로파일, 토큰, 경로가 남는 문제
  • 키체인 설정을 변경한 뒤 이전 작업이 복구되지 않는 문제

원격 맥을 새로 선택해야 한다면 VpsMesh의 원격 맥 환경처럼 접속 방식과 권한 범위를 먼저 확인하십시오. 필요한 것은 단순한 화면 공유가 아닙니다. SSH, 그래픽 세션, 재시작 뒤 복구, 키체인 보관 정책을 모두 검증할 수 있어야 합니다. Mac mini 기반 환경을 비교할 때는 Mac mini 원격 사용 안내도 함께 확인할 수 있습니다.

04

다섯 단계로 실제 배포 가능 여부를 판정합니다

1단계: 실패를 동일 커밋에서 재현합니다

의존성을 새로 바꾸기 전에 현재 커밋을 고정하십시오. flutter clean이나 캐시 삭제부터 실행하면 원래 원인과 환경 변화가 섞입니다. 그래픽 Xcode와 SSH에서 같은 스킴, 같은 릴리스 설정으로 각각 실행하고 로그를 보관하십시오.

2단계: 프로젝트와 타깃을 맞춥니다

Runner의 팀, 묶음 식별자, 릴리스 설정을 확인한 뒤 확장과 플러그인 타깃도 같은 방식으로 확인하십시오. flutter build ipa가 어떤 프로젝트와 스킴을 읽는지 명령 실행 위치와 설정 파일로 확인해야 합니다.

3단계: 서명 신원과 프로파일을 대조합니다

인증서와 개인 키가 함께 있는지, 키체인이 서명 신원을 인식하는지 확인하십시오. 그다음 프로파일의 앱 식별자, 배포 유형, 인증서, 기능이 현재 릴리스 타깃과 맞는지 비교합니다. 이 단계에서 폐기나 삭제를 실행하지 말고 백업과 회귀 계획을 먼저 세우십시오.

4단계: 아카이브와 아이파이를 분리해 검증합니다

아카이브가 만들어졌다면 내부 앱과 확장 산출물이 모두 있는지 확인하십시오. 그 뒤 아이파이를 내보내고 서명과 권한을 검증합니다. 파일이 생겼다는 사실은 성공 조건의 일부일 뿐입니다. 프로파일과 최종 권한 선언이 어긋나면 업로드 단계에서 다시 실패합니다.

5단계: 실제 업로드와 재실행을 확인합니다

테스트 업로드 또는 실제 배포 경로에서 검증을 끝내십시오. 한 번 성공한 뒤 SSH 연결을 끊고 다시 실행해 보십시오. 원격 맥을 재시작한 뒤에도 같은 저장소에서 아카이브, 아이파이 내보내기, 업로드가 가능한지 기록해야 합니다.

판정은 다음 조건으로 나누면 됩니다.

  • 같은 타깃에서 모든 경로가 실패하면 프로젝트 설정이나 서명 자산을 수정합니다.
  • 그래픽 세션만 성공하면 비대화형 키체인 접근과 로그인 세션을 수정합니다.
  • Runner는 성공하고 확장만 실패하면 확장 타깃의 식별자, 프로파일, 권한을 다시 구성합니다.
  • 아카이브는 성공하지만 업로드가 실패하면 내보내기 방식, 권한 선언, 배포 프로파일을 확인합니다.
  • 재부팅 뒤 복구되지 않으면 현재 환경을 상시 빌드 서버로 사용하지 말고 권한과 지속성이 맞는 다른 원격 맥 환경을 검토합니다.

핵심 통과 기준은 flutter build ipa 한 번의 종료 코드가 아닙니다. 릴리스 아카이브, 아이파이 내보내기, 서명 검증, 실제 업로드, 재연결 뒤 재실행까지 이어져야 합니다. Flutter의 iOS 배포 공식 절차와 Apple의 배포 준비 문서를 기준으로 각 단계의 증거를 남기십시오.

05

자주 발생하는 세부 판단

flutter build ipa에서 개발 팀 선택을 요구하면 실제 릴리스 스킴이 팀을 읽지 못하고 있는지 먼저 보십시오. 계정에 앱이 존재한다는 사실만으로 프로젝트 설정이 자동으로 고쳐지지는 않습니다.

Xcode에서 성공하고 SSH에서 실패하면 인증서를 다시 만들기 전에 키체인의 기본 설정과 잠금 상태를 비교하십시오. 반대로 그래픽 세션에서도 같은 오류가 나면 원격 접속 방식만 바꿔서는 해결되지 않습니다.

Runner와 플러그인 타깃은 동일한 팀 정책 안에 있을 수 있지만, 각자의 묶음 식별자와 권한에 맞는 서명 자료가 필요합니다. 마지막으로 검증 오류가 발생하면 소스 프로젝트 화면이 아니라 아카이브와 내보낸 아이파이 안의 실제 권한을 증거로 사용하십시오.

06

현재 컴퓨터와 원격 맥 중 어느 쪽이 맞는가

기존 Windows나 Linux 컴퓨터는 Flutter 공통 코드 작성에는 적합하지만 Xcode, Apple 서명 도구, iOS 아카이브를 직접 실행할 수 없습니다. 개인 Mac을 별도로 두면 장기간 안정적인 작업에는 유리하지만, 하드웨어 비용과 업데이트 관리, 항상 켜 두는 전력과 보안 관리가 따라옵니다.

반면 원격 맥은 필요한 기간만 사용할 수 있지만 네트워크 지연, 키체인 세션, SSH 재연결, 물리 기기 연결 여부를 확인해야 합니다. 프로젝트가 실제로 원격 환경에서 반복 배포되는지 먼저 검증한 뒤 장기 사용을 결정하는 편이 안전합니다.

따라서 현재 컴퓨터에서 Xcode 서명은 되지만 지속적인 iOS 배포 작업을 맡길 수 없다면, 같은 저장소를 권한이 완전한 원격 맥에서 아카이브·아이파이·업로드 순서로 시험하십시오. 이 세 단계가 재연결과 재시작 뒤에도 반복되면 임시 사용과 상시 Flutter 빌드 서버 중 어느 쪽이 필요한지 판단할 수 있습니다. 단기간 테스트나 출시에 맞춘 환경이 필요하다면 VpsMesh의 원격 맥 사용 조건을 확인하는 것이 구매 전에 더 현실적인 비교가 됩니다.