Swift Package Manager(SPM) 캐시를 안전하게 삭제하는 방법

SwiftPM 캐시는 한 가지가 아닙니다

Swift Package Manager는 다시 만들 수 있는 데이터를 범위별로 나눠 저장합니다. 명령줄 패키지의 .build 폴더에는 체크아웃, 저장소, 빌드 산출물, 작업 공간 상태가 들어 있고, 여러 프로젝트가 같은 의존성을 매번 네트워크에서 받지 않도록 공유하는 저장소 캐시도 따로 있습니다.

Xcode에는 계층이 하나 더 있습니다. 앱에서 Swift 패키지를 쓰면 패키지 체크아웃과 빌드 산출물이 보통 그 프로젝트의 DerivedData와 연결됩니다. 그래서 Xcode에서만 나타나는 패키지 문제는 같은 패키지를 swift 명령줄 도구로 빌드할 때와 다른 방법으로 정리해야 할 수 있습니다.

증상을 설명할 수 있는 가장 좁은 범위부터 정리하는 것이 원칙입니다. 빌드가 한 번 실패했다고 전역 캐시를 모두 지우지 마세요. 프로젝트 단위 정리는 복구가 빠르고, 네트워크 없이도 복구되는 경우가 많으며, 관련 없는 저장소를 느리게 만들지 않습니다.

알맞은 SwiftPM 명령 고르기

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 도구 체인에 따라 다릅니다. 이 Mac에서 지원되는 명령은 swift package --help로 확인하세요.

버전을 올릴 생각이 없다면 Package.resolved 보존하기

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

의존성을 새로 해석하는 것이 목적이라면 의도적인 문제 해결 단계가 될 수 있지만, 그만큼 조건이 달라집니다. 디스크 공간이나 산출물 재생성만이 목적이라면 Package.resolved를 남겨 두세요. 그래야 정리 작업이 모르는 사이에 의존성 업그레이드로 바뀌지 않습니다.

Package.swift는 소스이므로 캐시를 정리한다는 이유로 지우거나 고치지 마세요. 패키지의 Sources, Tests, 플러그인, 로컬 경로 의존성도 마찬가지입니다. .build에 생성된 내용은 다시 만들어지지만, 직접 작성한 파일은 되살릴 수 없을 수 있습니다.

Xcode에서 쓰는 Swift 패키지 정리하기

Xcode 프로젝트가 쓰는 패키지라면, 설치된 Xcode 버전에 File > Packages > Reset Package Caches 명령이 있을 때 먼저 실행하세요. 그다음 File > Packages > Resolve Package Versions로 프로젝트와 해석 파일에 기록된 의존성 그래프를 복원합니다. 메뉴 이름은 Xcode 버전마다 다를 수 있습니다.

문제가 그 프로젝트의 컴파일된 패키지 산출물에 있다면, Xcode의 Settings > Locations나 Finder에서 해당 프로젝트의 DerivedData 폴더만 삭제하세요. 앱과 패키지의 생성 결과물이 함께 지워지고, 이후 첫 빌드에서 다시 컴파일하고 인덱싱합니다. 한 프로젝트만 문제라면 DerivedData 전체를 지우지 말고 다른 활성 프로젝트의 폴더는 남겨 두세요.

Xcode를 여러 버전 설치했다면, 패키지를 다시 해석하기 전에 실제로 쓸 버전을 실행해 그 버전의 도구 체인과 플랫폼 지원으로 다시 빌드되게 하세요.

정리하기 전에 진단하기

공간이 문제라면 짐작하지 말고 .build 폴더와 공유 캐시를 측정하세요. 저장소들에서 .build 폴더를 찾아보면 더 이상 쓰지 않는 클론의 산출물이 보이는 경우가 많고, 지금 작업을 빠르게 해 주는 전역 캐시보다 이쪽이 더 나은 정리 대상입니다.

빌드 실패라면 원래 오류부터 기록하세요. 인증 실패, 접속할 수 없는 Git 호스트, 잘못된 패키지 매니페스트, 호환되지 않는 도구 버전, 체크섬 변경은 다운로드를 지운다고 해결되지 않습니다. 캐시를 지우면 오히려 단서가 사라지고 네트워크 실패가 하나 더 생길 수 있습니다.

정리한 뒤에는 swift package show-dependencies나 Xcode의 패키지 그래프를 예상한 해석 결과와 비교하세요. 의존성 해석이 성공했다고 끝내지 말고 관련 테스트까지 실행합니다. 의존성이 제대로 내려받아져도 배포 대상이나 도구 체인과 호환되지 않을 수 있습니다.

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

개발용 Mac에서는 쓰지 않게 된 저장소의 패키지 빌드 산출물을 골라 지우고, 전역 저장소 캐시는 다운로드 시간을 아껴 주는 동안 남겨 두세요. CI 러너는 다릅니다. 매번 새로 만드는 러너는 깨끗한 상태로 시작하면 되지만, 계속 유지되는 러너에는 크기 제한과 Swift 도구 체인·해석 상태를 포함한 캐시 키가 필요합니다.

purge-cache를 빌드 전에 습관처럼 실행하지 마세요. 재사용할 데이터를 버리고 네트워크 의존도를 높여, 속도 제한이나 외부 저장소 장애의 영향을 키웁니다. 측정 결과 비정상적으로 커졌거나 캐시 무결성 문제로 진단됐을 때, 또는 계속 유지되는 인프라에서 범위를 정한 유지 관리 작업으로만 실행하세요.

장애 기록에는 실행한 명령과 범위를 정확히 남기세요. ‘SwiftPM 캐시를 지웠다’는 모호합니다. ‘A 저장소에서 swift package clean을 실행했다’와 ‘전역 저장소 캐시를 비웠다’는 영향 범위와 복구 비용이 전혀 다릅니다.

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

AskClean은 SwiftPM 주변의 주요 개발자 저장 공간을 분류해 보여 줍니다. 프로젝트별 Xcode DerivedData, 저장소 빌드 산출물, npm 등 개발자 캐시, 시뮬레이터 저장 공간, 정체를 알 수 없는 큰 폴더가 여기에 포함됩니다. 각 항목을 다시 만들 수 있는지 설명하고, 삭제하기 전에 확인을 받습니다.

SwiftPM 캐시의 범위 자체는 공식 Swift 명령을 기준으로 판단하세요. AskClean은 주변의 어떤 분류가 공간을 차지하는지 찾는 데 유용하며, 정밀한 패키지 관리 작업을 설명 없는 일괄 삭제로 바꾸려는 도구가 아닙니다.

SwiftPM 명령별 범위

가장 강한 명령이 아니라 범위와 복구 비용에 맞는 명령을 고르세요.

자주 묻는 질문