Xcode 26.6 Swift Package Manager 의존성 해석 실패: 2026년 점검 가이드

Q: xcodebuild에서 Swift Package 버전을 고정하려면 어떻게 해야 하나요?

Package.swift의 버전 제약만 바꾸는 것으로는 충분하지 않습니다. 프로젝트가 생성한 Package.resolved를 검토하고 저장소에 함께 보존한 뒤, 자동 빌드가 같은 커밋과 같은 파일을 사용하도록 해야 합니다. xcodebuild의 의존성 해석 명령과 일반 빌드 명령을 분리해 기록하면 새 버전 선택으로 인한 변화를 발견하기 쉽습니다.

📌 Xcode 26.6에서 Swift Package Manager 의존성 해석이 실패할 때 먼저 확인해야 할 기준선과 분기 조건을 정리합니다. Package.resolved, xcodebuild, 저장소 인증, 캐시와 원격 맥 재현 환경을 순서대로 점검해 불필요한 환경 재구축을 피할 수 있습니다.

Xcode 26.6은 2026년 6월 25일 안정 버전으로 발표되었습니다. 공식 출시 기록을 기준으로 보면, 지금 필요한 것은 무작정 캐시를 지우는 일이 아닙니다.

증상 → 가장 빠른 해법
package resolution failed가 보이면 Xcode 버전, Package.resolved, 실제 해석 명령을 먼저 고정합니다.
원격 맥이나 자동 빌드에서만 실패하면 실행 사용자, SSH, Git 설정, 작업 경로를 먼저 비교합니다.

이 글은 Xcode 26.6으로 Swift Package를 포함한 iOS·macOS 앱을 빌드하는 독립 개발자를 위한 런북입니다.
비공개 패키지를 사용하는 개발자와 상시 iOS 빌드 서버를 운영하는 작은 팀도 대상입니다. 단순히 패키지를 추가하는 방법이나 캐시 삭제 명령 모음은 다루지 않습니다.

기준선 기록

먼저 실패한 작업을 다시 실행하기 전에 로그를 보존합니다. 아래 항목은 모두 비밀번호, 토큰, 저장소 주소와 사용자 이름을 가린 상태로 기록해야 합니다.

실제 Xcode 버전
활성 개발자 도구 경로
프로젝트 또는 워크스페이스 이름
실행한 xcodebuild 명령
첫 번째 유효 오류
실행 사용자와 작업 디렉터리
실패한 브랜치와 커밋

프로젝트 이름과 경로는 다음처럼 바꿔 적습니다.

<PROJECT_PATH>
<WORKSPACE_NAME>.xcworkspace
<SCHEME_NAME>
<REPOSITORY_URL>
<BUILD_USER>

Xcode 화면에서 패키지 해석을 실행한 결과와 명령줄 결과를 따로 보관합니다. 화면에서는 성공하지만 명령줄에서 실패하면 셸 환경, 개발자 도구 경로 또는 인증 정보가 다를 수 있습니다. 반대로 두 방식 모두 같은 저장소 오류를 낸다면 프로젝트 파일이나 의존성 그래프를 먼저 의심해야 합니다.

Apple의 일반적인 Xcode 설정 및 빌드 문제 점검 문서도 이처럼 오류를 한 단계씩 분리해 확인하는 접근을 전제로 합니다.

버전 그래프와 잠금 파일

Swift Package Manager의 결과는 Package.swift의 제약 조건만으로 결정되지 않습니다. 애플리케이션 프로젝트에서는 Package.resolved가 실제로 선택된 패키지 버전과 저장소 상태를 재현하는 핵심 자료가 됩니다.

다음 세 가지가 같은 상태를 설명하는지 비교합니다.

Package.swift의 의존성 주소와 버전 제약
프로젝트에 연결된 패키지와 제품
저장소에 있는 Package.resolved

브랜치를 바꾼 뒤 잠금 파일에 이전 브랜치의 패키지가 남을 수 있습니다. 병합 충돌을 잘못 해결해 같은 패키지에 중복 기록이 생길 수도 있습니다. 자동 업데이트 스크립트가 빌드 때마다 파일을 덮어쓰는지도 확인해야 합니다.

Apple은 패키지 의존성의 버전 제약 방식을 설명하고 있습니다. Swift Package Manager의 버전 해석 규칙 문서와 함께 읽으면, 제약 조건과 실제 잠금 결과를 구분하는 데 도움이 됩니다.

상시 빌드 환경에서는 다음 원칙이 안전합니다.

같은 커밋에서 같은 Package.resolved를 사용합니다.
빌드 시작 때 새 버전을 자동 선택하지 않습니다.
잠금 파일 변경은 코드 변경과 별도로 검토합니다.
애플리케이션 프로젝트와 재사용 라이브러리의 잠금 파일 정책을 구분합니다.

저장소 접근 계층

공개 패키지와 비공개 패키지는 같은 오류 문구를 보여도 원인이 다릅니다. 공개 패키지는 주소, DNS, 프록시와 연결 상태부터 봅니다. 비공개 패키지는 여기에 SSH 키, 호스트 지문, 저장소 권한과 키 로딩 상태가 추가됩니다.

실패 지점을 다음처럼 나눕니다.

연결 단계: 주소, DNS, 방화벽, 프록시
인증 단계: SSH 키, 키 에이전트, 액세스 권한
가져오기 단계: 브랜치, 태그, 커밋 존재 여부
해석 단계: 버전 제약과 잠금 파일의 충돌

xcodebuild가 내장 Git 설정과 시스템 Git 설정을 서로 다르게 읽는 상황도 고려해야 합니다. Apple의 지속적 통합 빌드 문서에 나온 해석 진입점과 명령을 기준으로 재현하고, 현재 작업이 읽는 설정 파일을 확인합니다.

SSH를 점검할 때 실제 값을 로그에 남기면 안 됩니다. 다음처럼 이름만 기록합니다.

<SSH_HOST>
<SSH_KEY_PATH>
<PRIVATE_REPOSITORY>
<BUILD_USER>

로컬에서는 성공하고 원격 맥에서만 실패하는 사례라면 먼저 패키지 버전을 바꾸지 마십시오. 원격 작업 사용자가 로그인한 계정과 다른지, SSH 에이전트가 없는지, 홈 디렉터리가 예상과 다른지 확인하는 편이 빠릅니다. 저장소 인증이 해결된 뒤에야 잠금 파일 문제를 판단할 수 있습니다.

캐시와 산출물 상태

캐시는 하나의 폴더가 아닙니다. 무엇을 지우는지에 따라 영향 범위와 복구 비용이 달라집니다.

대상	주로 영향을 받는 영역	먼저 확인할 변화
저장소 캐시	패키지 저장소를 다시 가져오는 과정	공개·비공개 저장소 연결
패키지 체크아웃	특정 패키지의 소스 상태	커밋과 태그 일치 여부
`DerivedData`	인덱스와 빌드 중간 결과	제품 연결과 컴파일 결과
빌드 산출물	이전 빌드 결과 재사용	새 Archive 재현 여부
서명 자료	인증서와 프로비저닝 설정	삭제 대상에서 제외

처음부터 전부 삭제하면 원인 비교가 불가능해집니다. 기존 캐시 상태에서 로그를 남기고, 새 작업 디렉터리에서 같은 커밋과 같은 잠금 파일을 사용해 결과를 비교합니다. 오류가 저장소 접근 단계에서 사라졌다면 패키지 캐시만 재설정할 수 있습니다. 해석은 성공하지만 제품이 사라진다면 DerivedData보다 프로젝트 연결을 먼저 확인해야 합니다.

인증서, 프로비저닝 프로파일, 키체인 자료는 패키지 캐시와 무관합니다. 복구 절차와 백업 여부를 확인하지 않은 상태에서 전체 홈 디렉터리를 지우지 마십시오.

의존성 그래프와 제품 연결

패키지 해석 성공은 앱 빌드 성공과 같은 뜻이 아닙니다. 상태를 다음처럼 분리해 기록해야 합니다.

의존성 버전 해석
소스 체크아웃
의존성 그래프 생성
Package Product 연결
컴파일
Archive

missing package product가 나온다면 네트워크를 반복해서 의심할 이유가 없습니다. 패키지 이름과 제품 이름이 다른지, 해당 제품이 현재 타깃에 연결됐는지, 로컬 패키지 오버라이드가 있는지 확인합니다.

바이너리 패키지를 사용한다면 체크섬 검증과 지원 플랫폼도 별도로 봐야 합니다. Apple의 바이너리 의존성 식별 문서를 기준으로 패키지의 실제 파일과 프로젝트가 기대하는 제품을 비교합니다.

특정 브랜치나 특정 스킴에서만 실패하면 최소 재현 프로젝트를 만듭니다. 같은 Package.resolved를 사용해 빈 프로젝트에서 해석하고, 원래 프로젝트에서만 실패하는지 확인합니다. 빈 프로젝트도 실패하면 저장소나 패키지 상태에 가깝습니다. 원래 프로젝트만 실패하면 타깃, 스킴, 로컬 패키지 경로를 우선 조사합니다.

조건별 복구 선택

아래 분기에서 조건을 만족하는 쪽부터 처리합니다.

같은 커밋과 Package.resolved로 Xcode와 xcodebuild가 모두 실패하면
저장소 주소, 버전 제약, 제품 연결을 함께 조사합니다. 캐시 전체 삭제는 뒤로 미룹니다.
Xcode 화면은 성공하지만 xcodebuild만 실패하면
실행 사용자, 활성 개발자 도구 경로, 셸의 Git·SSH 설정을 비교합니다.
공개 패키지만 실패하면
DNS, 프록시, 저장소 주소와 체크아웃 가능한 태그를 확인합니다.
비공개 패키지만 실패하면
SSH 키 로딩, 호스트 지문, 저장소 권한을 확인합니다. 로그에는 인증 값을 남기지 않습니다.
해석은 성공하고 제품 연결이나 컴파일에서 실패하면
패키지 제품, 타깃, 바이너리 체크섬을 조사합니다. 캐시 문제로 단정하지 않습니다.
캐시를 초기화해도 새 작업 디렉터리에서 같은 오류가 나면
버전 그래프와 저장소 접근을 다시 검증합니다.
로컬은 안정적이지만 원격 맥만 실패하면
원격 환경을 고정하기 전에 사용자와 작업 경로를 맞춥니다. 환경을 재구축하는 것은 마지막 선택입니다.

원격 맥 환경 검수

원격 맥을 iOS 빌드 서버로 사용할 때는 한 번의 성공보다 재현성이 중요합니다. 같은 저장소 커밋, 같은 Package.resolved, 같은 xcodebuild 명령으로 다음 작업을 연속 실행합니다.

의존성 해석
일반 빌드
Archive
결과 로그 보관
작업 디렉터리 정리 뒤 재실행
호스트 재시작 뒤 재실행
저장소를 새로 가져온 뒤 재실행

각 작업에서 실행 사용자와 홈 경로를 기록합니다. 로그인할 때만 로드되는 SSH 설정에 의존하면 무인 작업에서 다시 실패할 수 있습니다. Git 설정 파일과 SSH 설정 파일도 대화형 셸과 자동 작업에서 동일하게 읽히는지 비교합니다.

이 과정을 통과하면 원격 맥을 임시 빌드 환경으로 계속 사용할지, 고정된 상시 빌드 서버로 운영할지 판단할 수 있습니다. 반복 실패가 같은 저장소에서만 발생한다면 프로젝트 수정이 먼저입니다. 여러 작업에서 환경 차이가 반복되면 환경을 옮기거나 이중 빌드 환경을 유지하는 편이 안전합니다.

MACCOME의 원격 맥 이용 환경을 선택하는 경우에도 먼저 실제 프로젝트로 의존성 해석과 Archive를 검수해야 합니다. 단기 테스트라면 필요한 기간만 원격 맥을 사용하고, 장기적으로 같은 프로젝트를 계속 빌드한다면 캐시 보존과 재부팅 후 복구 절차를 계약 조건과 함께 확인해야 합니다.

독립 개발자용 점검 순서

다음 순서대로 진행하면 불필요한 재다운로드와 환경 재구축을 줄일 수 있습니다.

실패 로그에서 첫 번째 유효 오류를 표시합니다.
Xcode 버전과 활성 개발자 도구 경로를 저장합니다.
프로젝트 형식과 스킴을 확인합니다.
Package.swift와 Package.resolved의 관계를 검토합니다.
같은 커밋에서 화면 해석과 xcodebuild 해석을 비교합니다.
공개 패키지와 비공개 패키지의 접근 경로를 나눕니다.
실행 사용자, 홈 경로, Git, SSH 설정을 비교합니다.
캐시를 단계별로 비교하고 필요한 층만 초기화합니다.
제품 연결과 바이너리 의존성을 점검합니다.
새 작업 디렉터리와 재시작 뒤 Archive를 재현합니다.

현재 환경이 이미 불안정하고 상시 빌드가 필요하다면, 원격 맥에서 xcodebuild 자동 빌드를 구성하는 방법도 함께 확인해 보십시오. 다만 물리 장치 연결이나 장기 고정 부하가 핵심이면 직접 구매한 맥이 더 적합할 수 있습니다.

자주 찾는 해결 방법

위의 조건을 모두 확인했는데도 실패한다면 오류가 발생한 층을 다시 표시합니다. 의존성 해석 오류를 컴파일 오류로, 제품 연결 오류를 네트워크 오류로 분류하면 같은 명령을 반복하게 됩니다.

특히 원격 맥에서만 문제가 생기는 경우에는 패키지 버전을 바꾸기 전에 작업 사용자와 인증 설정을 고정해야 합니다. 잠금 파일이 저장소에 없거나 자동 작업이 이를 덮어쓴다면 버전이 계속 달라질 수 있습니다. 이때는 캐시보다 저장소 정책을 먼저 수정해야 합니다.

장기 운영에서는 iOS 빌드 서버의 의존성 캐시 관리 방법처럼 캐시 범위와 복구 절차를 문서화하는 것이 좋습니다. 캐시를 보존하는 목적은 삭제를 피하는 것이 아니라, 동일한 입력에서 같은 결과를 확인하기 위해서입니다.

자주 묻는 질문

Xcode에서 Swift Package 의존성을 해석하지 못하면 어디부터 확인해야 하나요?

먼저 실제로 실행된 Xcode 버전과 개발자 도구 경로, 프로젝트 형식, 첫 번째 유효 오류를 기록해야 합니다. 그다음 Xcode 화면에서 다시 해석하고 같은 저장소에서 xcodebuild 명령을 실행합니다. 두 결과가 다르면 의존성 자체보다 세션, 셸 환경, 작업 경로 또는 실행 사용자 차이일 가능성을 먼저 확인합니다.

`Package.resolved` 파일은 저장소에 커밋해야 하나요?

애플리케이션 프로젝트나 자동 빌드 저장소라면 일반적으로 커밋하는 편이 안전합니다. 이 파일은 해석된 버전과 저장소 상태를 재현하는 기준이 됩니다. 다만 재사용되는 라이브러리 자체와 애플리케이션 프로젝트는 처리 범위가 다를 수 있으므로, 프로젝트 구조에 맞는 정책을 정하고 검토 없이 파일을 덮어쓰는 자동화는 피해야 합니다.

로컬에서는 빌드되는데 원격 맥에서 의존성 해석이 실패하는 이유는 무엇인가요?

가장 흔한 차이는 실행 사용자와 작업 경로입니다. 원격 작업은 로그인 셸과 다른 Git 설정을 읽을 수 있고, SSH 키가 에이전트에 로드되지 않을 수도 있습니다. 저장소 주소, 네트워크 경로, 인증 정보, Xcode가 사용하는 개발자 도구 경로를 로컬과 원격에서 각각 기록하면 환경 차이와 실제 의존성 오류를 분리할 수 있습니다.

`xcodebuild`에서 Swift Package 버전을 고정하려면 어떻게 해야 하나요?

Package.swift의 버전 제약만 바꾸는 것으로는 충분하지 않습니다. 프로젝트가 생성한 Package.resolved를 검토하고 저장소에 함께 보존한 뒤, 자동 빌드가 같은 커밋과 같은 파일을 사용하도록 해야 합니다. xcodebuild의 의존성 해석 명령과 일반 빌드 명령을 분리해 기록하면 새 버전 선택으로 인한 변화를 발견하기 쉽습니다.

Package Cache를 초기화했는데도 같은 오류가 계속되면 어떻게 하나요?

캐시 전체를 다시 지우기보다 오류 단계부터 나눠야 합니다. 저장소 연결 실패라면 DNS, 프록시, SSH 인증을 확인하고, 제품을 찾지 못한다면 패키지 이름과 제품 이름, 대상 연결을 확인합니다. 해석은 성공했지만 빌드나 보관 단계에서 실패한다면 DerivedData와 바이너리 의존성 검증을 별도로 살펴봐야 합니다.

결론과 선택 기준

지금 사용하는 로컬 환경은 직접 통제할 수 있지만, 개발용 맥을 별도로 상시 운영하면 하드웨어 구매 비용, 저장 공간 관리, 전원과 재부팅 대응이 생깁니다. 일반적인 클라우드 빌드는 실행 환경과 캐시 정책을 세밀하게 통제하기 어렵고, 비공개 저장소 인증이나 특정 Xcode 조합에서 확인 범위가 제한될 수 있습니다.

문제가 로컬에 안정적인 macOS 환경이 없거나, 실행 사용자가 계속 달라지거나, 빌드 서버가 캐시를 보존하지 못해서 생긴다면 MACCOME의 원격 맥이 더 현실적인 선택일 수 있습니다. 반대로 장기간 일정한 고부하를 유지하거나 물리 장치를 직접 연결해야 한다면 자체 맥이 낫습니다. 임시 테스트와 반복 Archive가 목적이라면 실제 프로젝트로 먼저 검수한 뒤 필요한 기간만 MACCOME 원격 맥 환경을 사용하는 방식이 안전합니다.