Apple은 원격 binaryTarget의 checksum 계산 대상이 바이너리 아카이브라고 설명합니다. Apple의 checksum 문서에 맞춰 먼저 Package.swift의 URL이 가리키는 파일과 실제 다운로드된 ZIP이 같은 배포물인지 확인한 뒤, 그 파일의 checksum을 다시 계산하세요. 아카이브가 재압축되거나 교체됐다면 새 버전을 배포하고 선언도 함께 갱신해야 합니다. 캐시 삭제나 잠금 파일 수정만으로 해결하려 해서는 안 됩니다.

원격 XCFramework를 연결한 앱에서 검증 오류의 원인을 찾는 개발자에게 적합합니다.
Swift Package 바이너리를 배포하며 기존 파일과 URL을 관리하는 유지보수자도 확인할 수 있습니다.
Xcode 27 원격 빌드나 CI를 운영한다면, 같은 제출물에서 오류가 재현되는지 점검하는 기준으로 활용하세요.

마지막 업데이트: 2026년 10월 8일. Apple의 Xcode 27 릴리스 노트와 Swift Package 문서를 기준으로 확인했습니다. 이 글은 특정 환경의 실패를 Xcode 27 전체의 결함으로 간주하지 않습니다.

오류가 난 단계를 먼저 구분합니다

Swift Package Manager를 사용하는 프로젝트에서는 서로 다른 단계의 실패가 비슷한 빌드 오류로 보일 수 있습니다. 하지만 원인이 다르면 확인할 증거와 수정 방법도 달라집니다.

  • 소스 패키지 해석 실패: 패키지 버전이나 의존성 해석 결과부터 확인합니다. 아직 바이너리 ZIP의 체크섬 검증 단계에 도달하지 않았을 수 있습니다.
  • 원격 바이너리 체크섬 실패: 선언된 URL에서 가져온 아카이브의 내용이 manifest의 checksum과 일치하지 않는 경우입니다.
  • 다운로드 뒤 컴파일 실패: 바이너리를 받아 검증했지만 빌드 과정에서 실패한 경우입니다. 컴파일 로그를 확인해야 하며, 이를 checksum 오류로 처리하면 원인에서 멀어집니다.

오류 로그에 체크섬 불일치가 명시되어 있다면, 우선 실패한 패키지의 binaryTarget 선언과 실제 다운로드된 파일을 확보하세요. 네트워크 연결 실패나 컴파일 실패만으로 checksum 생성 오류라고 단정하지 않는 것이 중요합니다.

앱 개발자는 선언과 다운로드 ZIP을 대조합니다

다운로드된 ZIP과 선언의 checksum이 다르면 어떻게 확인하나요?

Package.swift에서 해당 binaryTarget의 이름, URL, checksum을 확인합니다. Apple 문서는 이 선언에 사용되는 인수가 이름, URL, checksum이라고 설명합니다. binaryTarget 인수 설명을 기준으로 세 값이 의도한 산출물과 일치하는지 확인하세요.

그다음 실패한 빌드가 실제로 요청한 URL과 응답 파일을 기록합니다. 선언에 적힌 URL과 비슷해 보이는 주소라도 리디렉션, 프록시, 파일 교체가 개입하면 받은 내용이 달라질 수 있습니다. 로그에 URL만 있고 파일을 식별할 기록이 없다면, 같은 제출물로 다시 받아 비교할 수 있도록 다운로드 경로와 오류 메시지를 보존하세요.

binaryTarget checksum은 어떤 파일에 계산하나요?

체크섬은 압축을 풀어 놓은 프레임워크 폴더가 아니라 URL이 제공하는 아카이브 파일 자체에 계산합니다. 배포자가 ZIP을 새로 만들거나 내용을 수정한 뒤 다시 압축했다면, 파일명이나 XCFramework 내부 구성이 같아도 아카이브의 바이트 내용은 달라질 수 있습니다. Apple은 배포하는 바이너리 프레임워크와 Swift Package의 관계를 바이너리 프레임워크 배포 문서에서 설명합니다.

올바른 입력 파일을 확보했다면 해당 파일에 대해 swift package compute-checksum을 실행합니다. Apple의 checksum 안내에 나온 계산 방식에 따라 출력값을 Package.swift의 선언과 비교하세요. 명령에 전달한 파일이 실제 배포 URL에서 제공되는 파일과 동일한지까지 확인해야 재계산 결과가 유효합니다.

패키지 배포자는 버전과 아카이브를 함께 검수합니다

배포 담당자에게 핵심은 checksum을 다시 구하는 것만이 아닙니다. checksum 계산 뒤 파일을 다시 압축했는지, 이미 공개한 URL의 대상 파일을 덮어썼는지, manifest가 다른 빌드 산출물을 가리키는지 함께 살펴야 합니다.

기존 버전의 URL이 어느 날 다른 파일을 반환하게 되면, 그 버전을 참조하는 프로젝트에서 이전과 다른 검증 결과가 나올 수 있습니다. 이전 배포물을 조용히 교체하기보다 새 버전을 발행하고 새 아카이브에 맞춰 manifest를 갱신하는 편이 안전합니다. Apple의 다중 플랫폼 바이너리 프레임워크 생성 문서를 참고해 배포할 XCFramework가 의도한 플랫폼과 구성을 담았는지도 검토하세요.

배포 검수에서는 다음 항목을 각각 증거로 남기면 좋습니다.

  • 아카이브를 생성한 소스 변경 사항과 빌드 결과
  • 공개한 URL과 실제로 내려받아 확인한 파일
  • 그 파일에 swift package compute-checksum을 실행한 결과
  • checksum이 포함된 Package.swift와 배포 버전의 대응 관계
  • 이전 버전 파일과 이를 사용하는 프로젝트의 복구 경로

이 과정을 하나의 검토 흐름으로 묶으면, 재압축 이후 오래된 checksum이 남거나 서로 다른 브랜치가 변경 가능한 URL을 공유하는 문제를 찾기 쉬워집니다.

원격 빌드 담당자는 제출물과 다운로드 경로를 확인합니다

바이너리를 업데이트했는데도 Xcode 27에서 계속 실패하면 어떻게 하나요?

새 checksum을 계산했더라도 빌드가 이전 파일을 가져오거나 다른 manifest를 읽으면 같은 오류가 이어질 수 있습니다. 프로젝트가 고정한 패키지 버전과 해결 결과를 확인하고, 해당 제출물의 빌드 로그에서 실제 요청 URL과 실패 단계를 살펴보세요. 네트워크 접근 문제, 리디렉션, 프록시에서 반환한 파일이 원인일 가능성과 checksum 선언 오류를 분리해야 합니다.

캐시 정리는 먼저 증거를 확보한 뒤 제한적으로 진행합니다. 기존 로그와 다운로드 파일을 보존하지 않고 캐시를 지우면 최초로 문제가 난 산출물과 이후의 정상 산출물을 구별하기 어려워질 수 있습니다. Apple의 CI에서 Swift Package를 사용하는 빌드 안내를 참고해 빌드에서 사용한 의존성 상태를 추적하고, 같은 제출물로 다시 검증하세요.

원격 맥 빌드에서 올바른 버전을 받았는지 어떻게 확인하나요?

로컬과 원격 환경에서 같은 저장소 제출물, 패키지 해결 상태, 요청 URL을 비교합니다. 원격 작업이 기대한 manifest와 버전을 사용했는지 확인하고, 실제로 받은 파일이 로컬에서 검증한 아카이브와 동일한지 대조하세요. 접근 가능한 URL이라는 사실만으로 올바른 파일을 받았다고 판단할 수는 없습니다.

문제가 반복된다면 로그에 다음 정보를 함께 남깁니다. 패키지 버전, 요청 URL과 응답 파일의 식별 정보, 검증이 중단된 단계, 빌드에 사용한 제출물입니다. 동일한 제출물로 깨끗한 환경에서 재실행해 같은 결과가 나오는지 확인하면, 우연히 남아 있던 로컬 캐시가 문제를 가렸는지도 구분할 수 있습니다.

수정 전에 실행할 수 있는 검수 목록

  • [ ] 오류가 소스 패키지 해석, 바이너리 아카이브 검증, 후속 컴파일 중 어느 단계에서 발생했는지 기록합니다.
  • [ ] Package.swift에서 대상 이름, URL, checksum을 확인하고 실패한 빌드가 사용한 선언을 보존합니다.
  • [ ] 선언된 URL에서 받은 ZIP이 배포자가 의도한 아카이브와 같은지 확인합니다.
  • [ ] 아카이브를 계산한 뒤 다시 압축하거나 교체하지 않았는지 배포 이력을 확인합니다.
  • [ ] 실제 배포 ZIP에 swift package compute-checksum을 실행하고 결과를 manifest와 대조합니다.
  • [ ] 파일이 바뀌었다면 기존 버전을 덮어쓰지 않고 새 버전과 새 선언을 함께 발행합니다.
  • [ ] 같은 제출물과 의존성 상태를 사용해 원격 환경에서 다시 빌드하고 결과를 기록합니다.

판정 기준은 간단합니다. URL이 가리키는 아카이브가 선언과 일치하면 이후 컴파일 단계의 오류를 따로 조사합니다. 파일이 바뀌었거나 다른 파일을 받았다면 새로 고정된 배포물을 만들고 그 파일의 checksum을 선언합니다. 캐시 삭제는 이 검증을 대신하지 않습니다.

역할별로 조치와 완료 기준을 나눕니다

담당 역할 우선 확인할 증거 수정 방향 완료 기준
앱 개발자 manifest의 URL과 실패 로그의 다운로드 주소 실제 파일과 선언을 대조하고 의존성 참조를 확인합니다 같은 제출물에서 체크섬 검증이 통과합니다
바이너리 패키지 배포자 배포 ZIP, 공개 URL, 계산 기록 변경된 파일은 새 버전으로 발행하고 checksum을 다시 선언합니다 URL, 아카이브, manifest의 대응을 재현할 수 있습니다
원격 빌드 담당자 저장소 제출물, 해결된 버전, 요청 URL, 실패 단계 네트워크 경로와 다운로드 파일을 로컬 결과와 비교합니다 깨끗한 원격 환경에서도 같은 제출물이 통과합니다

로컬 개발 환경만으로는 다운로드 경로나 캐시 상태가 일관되지 않을 수 있고, 기존 CI 환경은 프록시나 실행 작업의 기록을 확인하기 어려울 수 있습니다. 이 문제가 계속된다면 고정한 제출물로 깨끗한 macOS/Xcode 환경에서 비교 검증하는 방법도 고려할 수 있습니다. 다만 물리 장치 연결이나 장기간 고정된 로컬 작업이 꼭 필요하다면 원격 맥이 맞지 않을 수 있습니다. 그런 요구가 아니라 원격 빌드 재현과 검증 환경이 필요하고 사용할 macOS 환경이 없다면, RUVCLOUD의 원격 맥 환경과 이용 요금 안내를 살펴보고 현재 빌드 절차에 적합한지 판단하세요.