Xcodeのiosプロジェクトで「The sandbox is not in sync with the Podfile.lock」エラーを修正する

エラーの内容

ビルドを実行したら、何も起きない — いや、これが出た：

error: The sandbox is not in sync with the Podfile.lock. Run 'pod install' or update your CocoaPods installation.

完全に止まる。コードは1行もコンパイルされない。これはほぼ決まって、gitから新しいコードをプルした直後、ブランチを切り替えたとき、あるいはチームメイトがPodfileを更新してコミットしたのに、誰にもpod installを再実行するよう伝えなかったときに発生する。

なぜこうなるのか

CocoaPodsは依存関係をPods/ディレクトリ（「サンドボックス」）に保持する。Podfile.lockはそこにあるべき正確なバージョンを記録している — いわばレシートのようなものだ。レシートと実際の内容が一致しないと、Xcodeのビルドフェーズスクリプトがそれを検知して処理を拒否する。

よくあるきっかけ：

誰かがPodを追加・更新して新しいPodfile.lockをプッシュしたが、まだpod installを実行していない
Podのバージョンが異なるブランチに切り替えた
Pods/ディレクトリが削除されたか壊れた
チームメイトがpod installの代わりにpod update（バージョンをアップグレードする）を実行した
CocoaPods自体が更新されて、ロックファイルの形式が微妙に変わった

手順ごとの修正方法

ステップ1：pod install を実行する（80%はこれで解決）

Podfileがあるディレクトリ — 通常はプロジェクトのルート — から実行：

cd /path/to/your/project
pod install

完了したら、.xcodeprojではなく.xcworkspaceファイルを開く。必ずワークスペースを使うこと。再度ビルドすれば、おそらくこれで終わりだ。

ステップ2：specリポジトリを先に更新する

まだ失敗する？ローカルのCocoaPods specキャッシュが古くなっている可能性がある。インストール前に同期させよう：

pod repo update
pod install

古いspecは厄介だ — 成功を報告しながらpod installが更新を暗黙的にスキップすることがある。リポジトリの更新でCocoaPods CDNから最新のメタデータが取得される。

ステップ3：Podsディレクトリを削除して再インストールする

エラーが解消しない場合、Pods/ディレクトリ自体が壊れた状態になっている可能性が高い。削除してクリーンな状態から始めよう：

rm -rf Pods/
pod install

Podfile.lockはそのまま残るので、まったく同じバージョンが再インストールされる — 意図しないアップグレードの心配はない。

Podfileで指定した範囲内でバージョンアップグレードを許可したい場合のみ、Podfile.lockを削除する：

rm -rf Pods/
rm -f Podfile.lock
pod install

**これは慎重に扱うこと。**破壊的な変更をもたらす新しいバージョンのPodが取り込まれる可能性がある。

ステップ4：Xcodeの派生データを消去する

Xcodeはビルド成果物を積極的にキャッシュする。クリーンなpod installをしてもキャッシュの古いファイルが残り、エラーが消えないことがある。消去しよう：

rm -rf ~/Library/Developer/Xcode/DerivedData

GUIで操作したい場合は、Xcode内で：Settings → Locations → Derived Data → 矢印をクリック → プロジェクトのフォルダを削除。その後、Product → Clean Build Folder（Shift+Cmd+K）を実行してリビルドする。

ステップ5：CocoaPods自体を更新する

チームメンバー間のバージョン不一致が、微妙なロックファイルの非互換性を引き起こす。同僚がCocoaPods 1.15を使っていて、自分がまだ1.12を使っている場合、ロックファイルの形式が毎回このエラーを引き起こすほど異なることがある。

gemで更新する：

sudo gem install cocoapods

またはHomebrewで：

brew upgrade cocoapods

その後、pod installを再実行する。pod --versionでバージョンを確認し、チームと比較しよう。

ステップ6：Xcodeのビルドフェーズスクリプトを確認する

まれに、サンドボックスの同期を検証するビルドフェーズが壊れたり、誤って設定されたりすることがある。Xcodeを開いてターゲットを確認しよう：

Target → Build Phasesを選択
[CP] Check Pods Manifest.lockというフェーズを見つける
中のスクリプトはPODS_PODFILE_DIR_PATH/Podfile.lockとPODS_ROOT/Manifest.lockの差分を取る

見当たらない、または空の場合？CocoaPodsがビルドに正しく統合されていない。pod installを再実行すると、正しいビルドフェーズが自動的に再生成される。

確認方法

ビルドを信頼する前に、2つのロックファイルが実際に同期されているか確認しよう：

# 出力なし = ファイル一致 = 問題なし
diff Podfile.lock Pods/Manifest.lock

何も出なければ成功だ。何か出力されれば、まだ不一致がある — ステップ3に戻ろう。

インストール済みバージョンを再確認したい場合は：

pod list

Podfile.lockの内容と照合しよう。すべて一致しているはずだ。

今後の予防策

Podfile.lockは必ずコミットする — チームプロジェクトでは絶対に必要だ。全員が同一バージョンをインストールすることを保証する唯一の方法だ。
Pods/はgitに含めない — .gitignoreに追加しよう。各開発者がプル後にローカルでpod installを実行する。
プル時にpod installを習慣にする — diffにPodfileやPodfile.lockが含まれていたら、ビルド前に必ず実行しよう。
pod installとpod updateの違いを理解する — installはロックファイルを尊重し、updateは最新バージョンにアップグレードする。依存関係を意図的にアップグレードして結果をテストする準備ができている場合以外は、絶対にpod updateを実行しないこと。

クイックリファレンス

# 標準的な修正
cd /path/to/project
pod install

# クリーン修正（ロックされたバージョンを維持）
rm -rf Pods/
pod install

# 最終手段（バージョンアップグレードを許可）
rm -rf Pods/ Podfile.lock
pod install

# Xcodeキャッシュも消去する
rm -rf ~/Library/Developer/Xcode/DerivedData