Xcodeに「パッケージを解決中」と表示されたまま進まない、または追加したパッケージをダウンロードできない状態ですか。
最初にエラー文を保存し、通信・認証・バージョン制約・Package.resolved・ビルドのどこで止まったかを切り分けてください。 原因を確かめる前にキャッシュを消したり、授業で指定されたバージョンを変えたりせず、最後に元のプロジェクトで再解析とビルドを確認します。
iOSの教材に沿ってSwift Package Managerを追加したところ、Xcodeの解析やダウンロードで止まった学生向けです。
授業の依存バージョンを壊さずに、Package.resolvedの状態を確認したい人にも役立ちます。
学校のパソコンや遠隔Macを使っている場合も、通信、アカウント権限、プロジェクト設定のどこを見るかを整理できます。
01 Swift Package Managerの依存関係解決に失敗した場所を特定します
「パッケージを見つけられない」「取得の途中で止まる」「指定バージョンが合わない」「解析は終わったのにビルドに失敗する」は、同じ問題ではありません。Xcodeではパッケージの追加、依存関係の解析、プロジェクトのビルドを分けて確認します。まず画面に表示されたエラー全文と、止まった操作を記録してください。AppleのSwift packagesの説明では、Xcodeでパッケージを追加・管理する流れが案内されています。
| 表示や状態 | まず見る場所 | 次の判断 |
|---|---|---|
| パッケージが見つからない | リポジトリのURL、公開・非公開の別 | URLかアクセス権かを確かめます |
| ダウンロードが止まる | 接続状態、学校のネットワーク、認証 | 同じリポジトリにアクセスできるか確認します |
| 要求したバージョンを選べない | 授業の指定、依存パッケージの制約 | 指定を優先し、制約の食い違いを調べます |
| 解析成功後にビルドで失敗する | ビルドログ、ターゲット、必要な製品 | 通信の修復ではなく、プロジェクトの設定へ進みます |
赤いエラーが出たという理由だけで、ネットワークを原因と決めつけないことが大切です。Appleの説明でも、パッケージ依存関係の管理とアプリのビルドは別の作業として扱われています。
02 ダウンロード失敗は通信か認証かを分けます
公開パッケージに接続できない場合は、教材やプロジェクトに書かれたリポジトリURLに誤りがないか確認します。次に、ブラウザーやGitの利用可否ではなく、同じリポジトリのページに現在のアカウントでアクセスできるかを見ます。表示されるエラー文も、再試行する前に控えておきます。
| 状況 | 確認する内容 | 避ける対応 |
|---|---|---|
| 公開リポジトリに接続できない | URLの綴り、ネットワークの接続状態 | 原因不明のまま依存設定を変更する |
| 非公開リポジトリだけ取得できない | 招待状態、アカウント、認証情報 | アクセス制限を回避しようとする |
| 学校のネットワークで止まる | 学校側の制限や接続要件 | 管理者の許可なく制限や安全確認を無効にする |
非公開パッケージは、URLが正しくてもアクセス権がなければ取得できません。学校のネットワークで公開リポジトリへの接続もできない場合は、制限を回避せず、ネットワーク管理者に利用可能な方法を確認してください。
Swift Package Managerはパッケージを依存関係として追加し、条件に合うバージョンを解決します。Swift Package Managerの依存関係追加手順を確認し、教材の指定URLとXcodeに入力したURLが一致しているかを照合しましょう。
03 バージョン制約が合わないときは教材の指定を優先します
取得が始まるのに「要求されたバージョンを満たせない」と表示される場合は、通信よりもバージョン制約を調べます。パッケージの設定には、利用できるバージョンの範囲を指定する方法があります。たとえばSwiftのパッケージ説明では、from: "1.2.3"のような指定例と、バージョン制約の記述方法が示されています。PackageDescriptionのバージョン指定と照らし、数字を含む指定は教材やプロジェクトの記録にある値をそのまま確認してください。
授業の指定がある場合、解析を通すためだけに最低バージョンを引き上げたり、別のパッケージに置き換えたりしないでください。依存先の変更が、教材のコードやほかのパッケージとの組み合わせに影響することがあります。
確認する順序は次のとおりです。
- 教材の説明にあるパッケージURLとバージョン指定を確認します。
- プロジェクトが要求している範囲と、リポジトリで利用できるバージョンを見比べます。
- どの依存先が制約に合わないか、Xcodeのエラー文を読みます。
- 授業で指定された状態を変更する前に、担当教員や教材の更新情報を確認します。
Swiftの公式資料には、パッケージのバージョン指定と依存関係の記述方法がまとめられています。Swift PackageDescriptionの仕様を参照するときも、一般的な記述例と、いまのプロジェクトが要求する指定を混同しないようにしてください。
04 Package.resolvedと授業の依存バージョンがずれた場合
Package.resolvedは、解決済みの依存バージョンを記録し、プロジェクトやビルドの間で使うバージョンをそろえるためのファイルです。AppleのSwift packagesに関する資料をもとに、まずファイルがプロジェクト内のどこにあるか、Gitの変更一覧に出ているかを確認します。
授業のリポジトリに元のPackage.resolvedが含まれているなら、別のバージョンに更新する前に、手元のファイルが変更されていないかを見ます。削除は初手にしません。ロック結果を復元する場合と、依存バージョンを意図して更新する場合では、影響も確認方法も異なるためです。
- 授業の状態へ戻したい場合： 変更履歴や授業リポジトリの記録と手元のファイルを照合します。
- 依存関係を更新したい場合： 更新理由を記録し、作業前のファイルを保存してから、コードとビルド結果への影響を確認します。
ビルドを自動化する場合も、解決済みの依存関係を保つ方法が重要です。Appleのビルドワークフロー資料も参考に、Package.resolvedを単なる一時ファイルとして扱わず、プロジェクトで共有すべき状態かを確認してください。
05 解析後にビルドできない場合はログを切り替えて見ます
Swift Package Managerの解析が完了しているなら、同じダウンロード操作を繰り返すより、ビルドログの最初の具体的なエラーを確認します。必要な製品がターゲットに追加されているか、プロジェクトの対象プラットフォームが依存先の要件と合っているかも見直してください。
| 比較対象 | 結果から分かること | 次の作業 |
|---|---|---|
| 授業プロジェクト | そのプロジェクト固有の設定やコードが関係する可能性 | エラーが出たターゲットと製品を調べます |
| 最小構成の練習プロジェクト | 同じ依存先で問題が再現するか | 再現しなければ授業プロジェクト側を調べます |
| 同じ環境での別の作業 | 複数のプロジェクトで失敗するか | 共通する環境や接続条件を確認します |
最小構成のプロジェクトを使うのは、問題を切り分けるための比較です。授業のプロジェクトを書き換える前に、別の練習用プロジェクトで同じ依存先を試すと、プロジェクト固有の設定か、共通の環境かを区別しやすくなります。
06 元のプロジェクトで再解析とビルドを確認します
修正後は、次のチェック項目を上から確認してください。原因に関係しないファイルや設定を同時に変えないことで、直った理由も追いやすくなります。
- [ ] Xcodeのエラー全文と停止した工程を記録した。
- [ ] リポジトリURLと、公開・非公開の別を確認した。
- [ ] 必要なアカウント権限がある。学校のネットワーク制限は管理者に確認した。
- [ ] 授業で指定されたバージョン制約を、理由なく変更していない。
- [ ] Package.resolvedの変更状態と、授業側の記録を照合した。
- [ ] 修正した原因に対応するパッケージ解析を行った。
- [ ] 授業で使う元のプロジェクトをビルドし、エラーが残る場合はログを記録した。
Xcodeでのパッケージ管理は、授業の指定、依存バージョン、ロック結果を照らして進めます。作業手順や環境を切り分けたい場合は、CALMVPSの案内も確認できます。
学校の端末ではソフトウェアの導入権限が限られ、共有環境ではネットワークやアカウントの条件も自分だけで変えられないことがあります。個人のMacなら設定を管理できますが、購入や保守の負担があり、仮想環境では授業で必要なmacOS環境と同じ条件にならない場合もあります。依存関係のエラーだけなら、まずこの記事の切り分けを行ってください。互換性のあるmacOS環境で再現する必要があり、手元にMacがない場合は、CALMVPSの遠隔Macを短期間利用する方法も候補です。物理接続が必要な課題や、長期にわたり常時使う環境にはレンタルが適さないこともあるため、利用前にプランと料金を確認し、課題の要件に合うか判断してください。