Swift Package Manager 캐시를 안전하게 정리하는 방법

SwiftPM 캐시는 한 종류가 아니다

Swift Package Manager는 재생성 가능한 데이터를 여러 범위에 저장합니다. 명령줄 패키지의 .build에는 체크아웃, 저장소, 빌드 산출물과 작업 공간 상태가 있고, 여러 프로젝트가 재사용하는 공유 저장소 캐시도 있습니다.

Xcode는 한 계층을 더합니다. 앱에서 Swift Package를 쓰면 체크아웃과 빌드 산출물이 프로젝트 DerivedData에 연결될 수 있어 Xcode에서만 생기는 문제와 swift build 문제의 정리 위치가 다릅니다.

증상을 설명할 수 있는 가장 작은 범위부터 시작하세요. 한 번의 빌드 실패 때문에 전역 캐시를 모두 지우면 다른 저장소까지 느려집니다.

올바른 SwiftPM 명령 고르기

swift package clean은 현재 패키지의 빌드 산출물을 지웁니다. 오래된 컴파일 결과, 이상한 링크 문제, 한 저장소의 공간 정리에서는 먼저 이 명령을 사용합니다.

swift package reset은 현재 패키지의 캐시와 빌드 디렉터리 전체를 초기화합니다. clean보다 넓으며 의존성과 작업 공간 상태를 다시 준비해야 합니다. clean으로 고쳐지지 않는 로컬 상태 손상에 사용하세요.

swift package purge-cache는 SwiftPM의 전역 공유 저장소 캐시를 지웁니다. 여러 프로젝트가 네트워크에서 의존성을 다시 받아야 하므로 공유 캐시가 실제로 비대하거나 손상됐을 때만 사용합니다.

1. 소스 변경을 커밋하거나 stash하고 Package.swift와 Package.resolved를 확인합니다.
2. 패키지 루트에서 swift package clean을 실행하고 빌드를 다시 시도합니다.
3. 로컬 상태가 여전히 맞지 않으면 swift package reset 후 다시 해석하고 빌드합니다.
4. 공유 캐시 문제를 확인했을 때만 swift package purge-cache를 실행합니다.
5. Xcode DerivedData를 지우기 전에 의존성 그래프와 빌드를 확인합니다.

사용 가능한 하위 명령은 설치된 Swift 도구 체인에 따라 다릅니다. swift package --help로 확인하세요.

업데이트 의도가 없다면 Package.resolved 보존하기

Package.resolved는 다운로드 캐시가 아니라 의존성 해석 결과입니다. 앱 프로젝트에서 버전 관리하면 팀과 CI가 같은 버전을 사용합니다. 삭제하면 Package.swift가 허용하는 다른 버전이 선택될 수 있습니다.

새 해석이 목적이라면 의도적인 문제 해결 단계가 될 수 있지만 단순한 공간 정리와는 다릅니다. 산출물만 다시 만들 때는 남겨 두세요.

Package.swift, Sources, Tests, 플러그인과 로컬 경로 의존성은 소스입니다. .build는 재생성되지만 작성한 파일은 캐시가 아닙니다.

Xcode에서 쓰는 Swift Package 정리하기

해당 Xcode 버전에 File > Packages > Reset Package Caches가 있다면 먼저 실행하고 File > Packages > Resolve Package Versions로 프로젝트의 해석 상태를 복원합니다.

컴파일된 패키지 산출물만 문제라면 해당 프로젝트의 DerivedData만 삭제하세요. Xcode Settings > Locations에서 위치를 열고 다른 활성 프로젝트의 캐시는 남깁니다.

여러 Xcode를 설치했다면 실제 사용할 버전을 연 뒤 올바른 도구 체인과 플랫폼 지원으로 다시 해석합니다.

정리 전에 진단하기

공간 문제라면 .build와 공유 캐시를 측정하고 중단된 저장소의 산출물부터 처리하세요. 활성 프로젝트를 빠르게 하는 전역 캐시를 추측으로 버리지 않습니다.

빌드 문제라면 인증, Git 호스트, 잘못된 manifest, 도구 버전, 체크섬 오류를 먼저 기록하세요. 다운로드를 지워도 이런 원인은 해결되지 않습니다.

정리 후 swift package show-dependencies나 Xcode 그래프로 결과를 확인하고 관련 테스트를 실행합니다.

개발용 Mac과 CI 정책 구분하기

개발용 Mac에서는 사용하지 않는 저장소의 로컬 산출물을 선택적으로 지우고 공유 캐시가 시간을 아끼는 동안 보존합니다. 영구 CI Runner에는 크기 제한과 도구 체인·해석 상태를 포함한 캐시 키가 필요합니다.

purge-cache를 매 빌드 전 실행하지 마세요. 재사용을 버리고 네트워크 장애와 속도 제한의 영향을 키웁니다. 측정된 이상 증가나 무결성 문제 때만 사용합니다.

기록에는 한 저장소의 clean인지 전역 purge인지 정확한 범위를 남기세요.

AskClean으로 주변 개발자 저장 공간 찾기

AskClean은 프로젝트별 DerivedData, 저장소 산출물, npm 등 개발자 캐시, 시뮬레이터와 분류되지 않은 큰 폴더를 나눠 재생성 비용을 설명합니다.

SwiftPM 자체 범위는 공식 Swift 명령을 기준으로 삼으세요. AskClean은 무엇이 공간을 쓰는지 찾는 도구이지 정밀한 패키지 작업을 무차별 삭제로 바꾸지 않습니다.

SwiftPM 명령의 작용 범위

가장 강한 명령이 아니라 문제와 복구 비용에 맞는 범위를 고릅니다.

자주 묻는 질문