Sửa lỗi 'xcode-select: error: tool xcodebuild requires Xcode' — Thư mục Developer đang trỏ vào Command Line Tools

Chuyện gì đang xảy ra

Bạn chạy xcodebuild — hoặc một công cụ bọc ngoài nó như CocoaPods, Fastlane, Flutter hay lệnh build React Native — và nhận được lỗi sau:

xcode-select: error: tool 'xcodebuild' requires Xcode, but active developer directory '/Library/Developer/CommandLineTools' is a command line tools instance

Nói ngắn gọn: xcode-select đang trỏ vào Command Line Tools trong khi đáng lẽ phải trỏ vào ứng dụng Xcode đầy đủ. CLT là gói rút gọn — khoảng 700 MB — không có xcodebuild. Chỉ Xcode mới có.

Chẩn đoán vấn đề

Kiểm tra thư mục developer hiện tại đang trỏ vào đâu:

xcode-select -p

Nếu kết quả là /Library/Developer/CommandLineTools, đó chính là nguyên nhân. Nó phải trỏ vào bên trong Xcode bundle — thường là /Applications/Xcode.app/Contents/Developer.

Tiếp theo, xác nhận xem Xcode có thực sự được cài trên máy chưa:

ls /Applications/Xcode.app

Không có thư mục? Hãy cài Xcode trước. Thư mục tồn tại? Bạn chỉ cần chỉ cho xcode-select biết phải dùng nó.

Cách sửa

Tùy chọn 1: Xcode đã được cài (Trường hợp phổ biến nhất)

Một lệnh là xong:

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

Sau đó chấp nhận thỏa thuận giấy phép Xcode. Một số công cụ thất bại âm thầm nếu bỏ qua bước này — chỉ mất hai giây mà tránh được nhiều đau đầu về sau:

sudo xcodebuild -license accept

Xong rồi. Chuyển xuống phần Xác minh bên dưới.

Tùy chọn 2: Xcode chưa được cài

Cài Xcode từ Mac App Store. Dự tính 20–40 phút tùy tốc độ mạng — bản tải về nặng 10–15 GB. Nếu cần phiên bản cụ thể để khớp với setup của team, hãy tải thẳng từ cổng thông tin nhà phát triển của Apple.

Sau khi cài xong:

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license accept

Tùy chọn 3: Xcode được cài ở đường dẫn không chuẩn

Đổi tên ứng dụng? Chạy song song bản ổn định với bản beta? Đường dẫn sẽ khác. Tìm xem bạn có gì:

# Liệt kê tất cả các bản Xcode đã cài
ls /Applications/ | grep -i xcode

# Trỏ đến đúng phiên bản cần dùng
sudo xcode-select -s /Applications/Xcode_16.app/Contents/Developer

Xác minh kết quả

Chạy cả hai lệnh sau:

# Lúc này sẽ hiển thị đường dẫn đến Xcode app
xcode-select -p
# Kết quả mong đợi: /Applications/Xcode.app/Contents/Developer

# Sẽ in ra phiên bản Xcode rõ ràng
xcodebuild -version
# Kết quả mong đợi:
# Xcode 16.x
# Build version 16Cxxx

Nếu lỗi ban đầu xuất hiện qua CocoaPods, Fastlane hay Flutter, hãy chạy lại công cụ đó. Lỗi xcode-select sẽ biến mất.

Tại sao lỗi này cứ xảy ra

Thứ tự cài đặt thường là thủ phạm. Homebrew, git và một số công cụ khác yêu cầu Command Line Tools trên Mac mới — nên CLT được cài trước. Khi bạn cài Xcode đầy đủ sau đó, macOS không tự động cập nhật con trỏ xcode-select. Đường dẫn CLT cũ cứ nằm đó cho đến khi bạn đổi thủ công.

Nâng cấp macOS lớn là nguyên nhân phổ biến thứ hai. Sonoma, Sequoia — nhiều phiên bản trong số đó đã reset thư mục developer về CLT dù mọi thứ đã được cấu hình đúng trước khi nâng cấp.

Bài học rút ra

• Mỗi khi cài hoặc cập nhật Xcode, chạy ngay sudo xcode-select -s /Applications/Xcode.app/Contents/Developer. Chỉ mất năm giây. Tránh được cả buổi debug như thế này.
• Sau mỗi lần nâng cấp macOS lớn, kiểm tra xcode-select -p trước khi động vào bất kỳ build iOS hay macOS nào.
• Build thất bại với biến thể nào đó của "requires Xcode"? Kiểm tra xcode-select -p trước. Chín trong mười lần, nó đang trỏ vào CLT.
• Flutter, React Native CLI, Fastlane và CocoaPods đều gọi xcodebuild nội bộ. Công cụ khác nhau, lỗi như nhau, cách sửa như nhau.