Sửa lỗi 'The sandbox is not in sync with the Podfile.lock' trong dự án iOS Xcode

Lỗi Gặp Phải

Bạn nhấn Build. Không có gì xảy ra — ngoại trừ thông báo này:

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

Dừng hẳn. Không một dòng code nào được biên dịch. Lỗi này hầu như luôn xảy ra ngay sau khi pull code mới từ git, chuyển branch, hoặc khi một thành viên trong nhóm đã cập nhật Podfile và commit thay đổi mà không thông báo cho ai chạy lại pod install.

Nguyên Nhân

CocoaPods lưu trữ các dependency trong thư mục Pods/ (hay còn gọi là "sandbox"). File Podfile.lock ghi lại chính xác các phiên bản cần có — hãy coi nó như một tờ biên lai. Khi biên lai và nội dung thực tế không khớp nhau, script trong build phase của Xcode sẽ phát hiện ra và từ chối tiếp tục.

Các nguyên nhân phổ biến nhất:

Ai đó đã thêm hoặc cập nhật một Pod và push Podfile.lock mới, nhưng bạn chưa chạy pod install
Bạn chuyển sang branch khác có phiên bản Pod khác nhau
Thư mục Pods/ bị xóa hoặc bị hỏng
Một thành viên chạy pod update (nâng cấp phiên bản) thay vì pod install
Bản thân CocoaPods được cập nhật và tạo ra định dạng lockfile hơi khác

Cách Khắc Phục Từng Bước

Bước 1: Chạy pod install (giải quyết được 80% trường hợp)

Từ thư mục chứa Podfile của bạn — thường là thư mục gốc của project:

cd /path/to/your/project
pod install

Sau khi hoàn tất, hãy mở file .xcworkspace — không phải .xcodeproj. Luôn luôn dùng workspace. Build lại và nhiều khả năng bạn đã xong.

Bước 2: Làm mới spec repo trước

Vẫn còn lỗi? Cache spec CocoaPods trên máy bạn có thể đã cũ. Hãy đồng bộ lại trước khi cài đặt:

pod repo update
pod install

Spec cũ rất khó phát hiện — chúng có thể khiến pod install bỏ qua các bản cập nhật trong khi vẫn báo thành công. Lệnh repo update sẽ kéo metadata mới nhất từ CDN của CocoaPods.

Bước 3: Xóa thư mục Pods và cài lại từ đầu

Khi lỗi vẫn còn, bản thân thư mục Pods/ có thể đang ở trạng thái xấu. Hãy xóa nó đi và bắt đầu lại từ đầu:

rm -rf Pods/
pod install

Thao tác này giữ nguyên Podfile.lock của bạn, nên bạn sẽ cài lại đúng những phiên bản đó — không có nâng cấp bất ngờ.

Chỉ xóa Podfile.lock nếu bạn muốn cho phép nâng cấp phiên bản trong phạm vi mà Podfile của bạn đã chỉ định:

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

Hãy cẩn thận với lệnh này. Nó có thể kéo về các phiên bản Pod mới hơn mà có thể gây ra các thay đổi phá vỡ tương thích.

Bước 4: Xóa derived data của Xcode

Xcode cache các artifact build rất tích cực. Đôi khi các file cache cũ vẫn tồn tại sau khi pod install sạch và tiếp tục gây ra lỗi. Hãy xóa chúng đi:

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

Thích dùng giao diện hơn? Trong Xcode: Settings → Locations → Derived Data → nhấn mũi tên → xóa thư mục project của bạn. Sau đó nhấn Product → Clean Build Folder (Shift+Cmd+K) và build lại.

Bước 5: Cập nhật bản thân CocoaPods

Sự khác biệt phiên bản giữa các thành viên trong nhóm gây ra sự không tương thích lockfile tinh vi. Nếu đồng nghiệp bạn đang dùng CocoaPods 1.15 còn bạn vẫn dùng 1.12, định dạng lockfile có thể khác nhau đủ để kích hoạt lỗi này mỗi lần.

Cập nhật bằng gem:

sudo gem install cocoapods

Hoặc qua Homebrew:

brew upgrade cocoapods

Sau đó chạy lại pod install. Kiểm tra phiên bản của bạn bằng pod --version và so sánh với các thành viên trong nhóm.

Bước 6: Kiểm tra script build phase trong Xcode

Hiếm khi xảy ra, nhưng build phase xác thực đồng bộ sandbox có thể bị hỏng hoặc cấu hình sai. Mở Xcode và xem target của bạn:

Chọn Target → Build Phases
Tìm phase có tên [CP] Check Pods Manifest.lock
Script bên trong thực hiện so sánh giữa PODS_PODFILE_DIR_PATH/Podfile.lock và PODS_ROOT/Manifest.lock

Bị thiếu hoặc trống? CocoaPods chưa được tích hợp đúng cách vào quá trình build. Chạy lại pod install sẽ tự động tạo lại các build phase chính xác.

Xác Minh Kết Quả

Trước khi tin tưởng vào kết quả build, hãy xác nhận hai file lock thực sự đang đồng bộ:

# Không có output = các file khớp nhau = bạn đã ổn
diff Podfile.lock Pods/Manifest.lock

Im lặng là thành công. Bất kỳ output nào đều có nghĩa là vẫn còn sự không khớp — hãy xem lại Bước 3.

Muốn kiểm tra lại các phiên bản đã cài đặt? Chạy:

pod list

Đối chiếu với nội dung trong Podfile.lock. Mọi thứ phải khớp nhau.

Phòng Tránh Lỗi Trong Tương Lai

Luôn commit Podfile.lock — bắt buộc với các project nhóm. Đây là cách duy nhất để đảm bảo mọi người cài đặt đúng cùng một phiên bản.
Đưa Pods/ vào gitignore — thêm vào .gitignore. Mỗi developer tự chạy pod install trên máy mình sau khi pull.
Tạo thói quen chạy pod install sau mỗi lần pull — bất cứ khi nào bạn thấy Podfile hoặc Podfile.lock trong diff, hãy chạy nó trước khi build.
Hiểu sự khác biệt giữa pod install và pod update — install tuân thủ lockfile; update nâng cấp lên phiên bản mới nhất. Không bao giờ chạy pod update trừ khi bạn có chủ đích nâng cấp dependency và sẵn sàng kiểm tra kết quả.

Tóm Tắt Nhanh

# Cách sửa tiêu chuẩn
cd /path/to/project
pod install

# Sửa sạch (giữ nguyên phiên bản đã khóa)
rm -rf Pods/
pod install

# Tùy chọn triệt để (cho phép nâng cấp phiên bản)
rm -rf Pods/ Podfile.lock
pod install

# Đồng thời xóa cache Xcode
rm -rf ~/Library/Developer/Xcode/DerivedData