Swift Package Manager のキャッシュを安全に削除する方法

SwiftPM のキャッシュは一つではない

Swift Package Manager は、作り直せるデータを範囲の異なる複数の場所に保存します。コマンドラインのパッケージには通常 .build ディレクトリがあり、チェックアウト、リポジトリ、ビルド出力、ワークスペースの状態が入っています。さらに SwiftPM は、複数のプロジェクトが同じ依存関係を毎回ネットワークから取得しなくて済むよう、共有のリポジトリキャッシュも保持しています。

Xcode では、もう 1 つ層が加わります。アプリで Swift パッケージを使う場合、パッケージのチェックアウトとビルド成果物は、そのプロジェクトの DerivedData に置かれることが多くなります。そのため、Xcode の中だけで起きるパッケージの問題は、同じパッケージを swift コマンドでビルドした場合とは別の場所を掃除する必要があるかもしれません。

いちばん安全なのは、症状を説明できるもっとも狭い層だけを掃除することです。ビルドが一度失敗しただけで、グローバルキャッシュをすべて消すのはやめましょう。プロジェクト単位の掃除なら復旧が速く、オフラインでも済むことが多く、関係のないリポジトリを遅くすることもありません。

目的に合う SwiftPM コマンドを選ぶ

SwiftPM には、範囲が意図的に異なる 3 つのコマンドがあります。swift package clean は現在のパッケージのビルド成果物を削除します。古いコンパイル結果、原因の分からないリンクの問題、1 つのリポジトリに限った容量の整理では、最初に使うコマンドです。

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 だけを削除します。アプリとパッケージの生成物がまとめて消え、その後の最初のビルドで再コンパイルとインデックスの再作成が行われます。

影響を受けているのが 1 つのプロジェクトだけなら、DerivedData のルート全体は削除しないでください。現役のプロジェクトのキャッシュは残し、該当するプロジェクトのフォルダだけを削除します。複数の Xcode をインストールしている場合は、パッケージを解決し直す前に使うバージョンを起動し、そのツールチェーンとプラットフォームサポートで再ビルドされるようにしてください。

消す前に診断する

容量対策なら .build と共有キャッシュを測定し、使わなくなったリポジトリの成果物から処理します。現役プロジェクトを高速化している全体キャッシュを推測で捨てないでください。

ビルド障害なら最初のエラーを記録します。認証、Git ホスト、無効な manifest、ツールバージョン、チェックサムの問題は、ダウンロードを消しても直りません。キャッシュを消すと原因の手がかりが失われ、ネットワークの問題がもう 1 つ増えることもあります。

掃除後は swift package show-dependencies や Xcode のグラフで解決結果を確認し、関連テストを実行します。ダウンロード成功だけでは、ツールチェーンや配備ターゲットとの互換性は証明できません。

開発用 Mac と CI の運用を分ける

開発用 Mac では、使わなくなったリポジトリのローカルなビルド成果物だけを削除し、共有キャッシュはダウンロード時間を節約している間は残します。CI は事情が異なります。使い捨てのランナーは毎回まっさらな状態で始められますが、常設のランナーにはサイズの上限と、Swift ツールチェーンと解決状態を含むキャッシュキーが必要です。

purge-cache をビルド前の決まった手順にしないでください。再利用できるデータを捨て、ネットワークへの依存を増やし、レート制限や配布元の障害の影響を大きくします。実行するのは、測定で異常な増加が分かったとき、キャッシュの整合性が原因と診断されたとき、または常設の環境で範囲を決めた保守作業として行うときに限ります。

障害記録には範囲を明記します。「SwiftPM キャッシュを消した」ではなく、「リポジトリ A で clean」か「グローバルキャッシュを purge」かを区別してください。この 2 つは、影響範囲も復旧のコストもまったく違います。

AskClean で周辺の開発者ストレージを探す

AskClean は、SwiftPM の周辺にある主な開発者ストレージを一覧にできます。プロジェクト別の Xcode DerivedData、リポジトリのビルド成果物、npm などのパッケージキャッシュ、シミュレータのストレージ、正体の分からない大きなフォルダなどです。項目ごとに作り直せるかどうかを説明し、削除する前に必ず確認を求めます。

SwiftPM のキャッシュの範囲については、公式の Swift コマンドを基準にしてください。AskClean は周辺のどのカテゴリが容量を使っているかを見つけるのに役立ちますが、パッケージマネージャによる精密な操作を、理由の分からない一括削除に置き換えるものではありません。

SwiftPM コマンドの作用範囲

いちばん強力なコマンドではなく、範囲と復旧のコストで選びます。

よくある質問