Cài Đặt và Cấu Hình Xcode: Bước Khởi Đầu Cho Hành Trình Phát Triển iOS

Xcode tải xong không có nghĩa là Xcode dùng được. Lần mở đầu tiên thường chặn bạn ở bốn chỗ: chưa nhận license, command line tools vẫn trỏ bản Xcode cũ, simulator chưa có runtime iOS 27.2, và project không có signing team. Cả bốn đều báo lỗi trông như lỗi code, nên người mới hay mất nửa ngày để đoán. Dưới đây là quy trình cài đặt và cấu hình Xcode 27.2 trên macOS 27.2, kèm lệnh kiểm tra để bạn luôn biết mình đang chạy bản nào.

Cập nhật 2026: bốn điểm đã khác

  • Xcode 27.2 (build 27B52, 29/10/2026) là bản ổn định; Xcode 27.3 beta ra ngày 03/11/2026. iOS 27.2 (24B119) phát hành 26/10/2026, iOS 27.3 đang beta.
  • Xcode 27 chạy trên dòng macOS 27 (hiện tại 27.2); không cài được lên macOS 26. Đừng nâng macOS giữa sprint gần release.
  • Quản lý thiết bị và simulator gom vào Device Hub của Xcode 27, thay cho cửa sổ Devices and Simulators mà tutorial cũ mô tả.
  • Swift 6.4.2 là toolchain hiện tại; SwiftPM từ 6.4 dùng Swift Build làm build system mặc định, nên output của swift build không còn giống hệt bản 5.x.

Trước khi cài đặt và cấu hình Xcode: máy, macOS, dung lượng

Xcode là bộ SDK nhiều GB, chưa kể runtime simulator tải thêm. Kiểm tra đĩa trước khi bấm tải để không gặp lỗi hết dung lượng giữa lúc giải nén.

Hạng mục Mức năm 2026 Ghi chú
macOS 27.x (hiện tại 27.2) Xcode 27 không chạy trên macOS 26
Chip và RAM Apple silicon, 16 GB trở lên 8 GB vẫn build được nhưng simulator rất chậm
Dung lượng trống 50 GB tối thiểu, 100 GB thoải mái Tính cả file .xip, Xcode.app, runtime và DerivedData
df -h /
du -sh ~/Library/Developer/Xcode 2>/dev/null

df -h / cho biết dung lượng trống trên volume khởi động. Dưới 30 GB thì dọn trước: runtime cũ, DerivedData, bản Xcode không dùng. Cài khi đĩa gần đầy là cách nhanh nhất để gặp lỗi khó hiểu lúc giải nén.

Kênh tải: App Store hay developer.apple.com?

Hai kênh cho cùng một sản phẩm nhưng khác nhau ở quyền kiểm soát phiên bản. App Store luôn đưa bạn bản ổn định mới nhất; trang developer cho phép chọn đúng bản, kể cả bản cũ và beta.

Kênh Bạn nhận được Dùng khi
Mac App Store Xcode 27.2, cập nhật tự động, không có beta hay bản cũ Máy cá nhân chỉ cần một Xcode
developer.apple.com (.xip) Mọi bản từ cũ đến 27.3 beta, cần Apple ID Cần beta, cần nhiều bản song song, máy CI

File .xip là archive có chữ ký; lúc mở, nó giải nén và chiếm thêm dung lượng tương đương. Đặt bản beta ở tên riêng như Xcode-27.3-beta.app, đừng đặt trùng Xcode.app: bản beta không nộp được lên App Store Connect nên phải là bản phụ.

Lần mở đầu tiên: license, additional components, command line tools

Ba lệnh dưới đây xử lý phần Xcode chỉ hỏi bằng dialog: license, thành phần bổ sung, trạng thái first launch. Cần mật khẩu quản trị.

sudo xcodebuild -license accept
sudo xcodebuild -runFirstLaunch
xcodebuild -checkFirstLaunchStatus

-license accept ghi nhận bạn đồng ý thỏa thuận; thiếu bước này, mọi lệnh xcodebuild sau đó dừng với thông báo “You have not agreed to the Xcode license agreements”. -runFirstLaunch cài các package bổ sung (mô phỏng thiết bị, công cụ chuyển đổi, SDK thành phần) mà Xcode cần để build. -checkFirstLaunchStatus trả mã 0 khi xong; chạy lại nếu quá trình cài bị treo.

Command line tools đã nằm trong Xcode.app: không cần xcode-select --install nếu đã cài Xcode đầy đủ. Lệnh đó cài bộ CLT rời ở /Library/Developer/CommandLineTools; chạy song song hai bộ là nguồn lỗi “dùng nhầm SDK”.

xcode-select -p
# /Applications/Xcode.app/Contents/Developer
xcrun --find swift
# /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/swift

Nếu xcode-select -p trả về /Library/Developer/CommandLineTools, bạn đang ở bộ CLT rời và sẽ không thấy SDK iOS. Sửa bằng lệnh ở phần sau.

Chọn Xcode mặc định khi máy có nhiều bản

/Applications/Xcode.app chỉ là một thư mục. Thứ quyết định là biến trạng thái mà xcode-select ghi lại; đổi nó là đổi toolchain cho Terminal, script build và CI trên máy đó.

xcodebuild -version
# Xcode 27.2
# Build version 27B52

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

xcode-select -p
# /Applications/Xcode-27.3-beta.app/Contents/Developer
sudo xcode-select -s /Applications/Xcode-27.3-beta.app

Với một lệnh duy nhất, không đụng cấu hình máy, dùng DEVELOPER_DIR. Đây cũng là cách CI pin phiên bản Xcode mà không cần quyền sudo.

DEVELOPER_DIR=/Applications/Xcode-27.3-beta.app/Contents/Developer xcodebuild -version
DEVELOPER_DIR=/Applications/Xcode-27.3-beta.app/Contents/Developer xcrun simctl list runtimes

Quy tắc: mặc định toàn máy là 27.2; beta chỉ bật bằng DEVELOPER_DIR trong shell hoặc scheme riêng. Đảo ngược lại là pitfall số một: build từ Terminal lặng lẽ dùng SDK beta trong khi giao diện vẫn mở bản ổn định.

Simulator: runtime iOS 27.2 và Device Hub

Xcode 27 tách việc tải runtime khỏi việc cài IDE: Xcode 27.2 không tự kèm runtime iOS 27.2. Chưa tải thì danh sách destination trống và build báo không có thiết bị phù hợp.

xcodebuild -downloadPlatform iOS
xcrun simctl list runtimes
# iOS 27.2 (24B119) - com.apple.CoreSimulator.SimRuntime.iOS-27-2
xcrun simctl list devices available

Trong Xcode 27, Device Hub (menu Window > Device Hub) là nơi xem thiết bị thật đã pair, simulator đã tạo và runtime đã cài. Tạo simulator ở đó hoặc bằng lệnh, rồi boot mà không cần mở app Simulator trước:

DEVICE=$(xcrun simctl list devices available | grep -m1 "iPhone" | grep -oE "[0-9A-F-]{36}")
xcrun simctl boot "$DEVICE"
open -a Simulator
xcrun devicectl list devices

Lấy UDID thay vì tên thiết bị: tên có thể trùng giữa nhiều runtime, UDID thì không. xcrun devicectl list devices là CLI của Device Hub cho thiết bị thật, dùng được khi không mở IDE.

Sau khi nâng Xcode, simulator của runtime cũ vẫn nằm đó và hiện là “unavailable”. Dọn chúng, đừng để tích tụ:

xcrun simctl delete unavailable
xcrun simctl erase all

Apple ID, team và signing

Chạy trên simulator không cần signing. Chạy trên iPhone thật thì cần, và đây là lỗi hay gặp nhất ở lần build đầu: “Signing for ‘App’ requires a development team”.

Mở Xcode > Settings > Accounts, bấm +, chọn Apple ID, đăng nhập. Tài khoản miễn phí đủ để ký và chạy app trên máy mình; profile của nó có hạn nên phải ký lại định kỳ. Tài khoản thuộc Apple Developer Program mới tạo được profile phân phối, đẩy TestFlight và dùng Xcode Cloud. Rồi vào target > Signing & Capabilities, tick Automatically manage signing và chọn Team.

security find-identity -v -p codesigning

Lệnh này liệt kê chứng chỉ ký trong Keychain. Nếu danh sách rỗng mà Xcode báo thiếu team, tài khoản chưa được thêm chứ không phải lỗi mạng. Đừng commit .p12 hay profile: mỗi máy tự tạo chứng chỉ từ Team.

Settings: font, Source Control, Locations, DerivedData

Phần cấu hình này không bắt buộc để build, nhưng làm đúng một lần thì tiết kiệm nhiều giờ về sau. Mở Xcode > Settings.

Text Editing và Source Control

Tab Text Editing chứa font, cỡ chữ, thụt lề, kiểm tra chính tả. Chọn font monospaced hỗ trợ tiếng Việt đủ dấu — nhiều font đẹp nhưng dấu bị lệch dòng. Tab Source Control khai báo author name/email (phải khớp danh tính GitHub nếu muốn commit hiện đúng), bật auto-fetch, và bật ignore mặc định để xcuserdata, .DS_Store không vào repo.

Locations và DerivedData

Tab Locations quyết định ba đường dẫn: DerivedData, Archives và Command Line Tools. Để mặc định là ổn, nhưng phải biết nó ở đâu khi cần dọn. Thư mục chứa build product, index, module cache — xóa được bất cứ lúc nào, chỉ mất thời gian build lại.

du -sh ~/Library/Developer/Xcode/DerivedData
rm -rf ~/Library/Developer/Xcode/DerivedData/*

Dự án lớn hoặc nhiều branch nên đặt DerivedData theo project để tránh lẫn cache; chỉ định bằng -derivedDataPath và .gitignore thư mục đó:

xcodebuild -scheme EvotekNotes -derivedDataPath build clean build

Archives thì khác: đó là nơi lưu bản build để nộp App Store, có ký và có dSYM. Đừng xóa mù; chỉ xóa archive cũ khi chắc không cần đọc crash log từ bản đó.

xcodebuild và simctl: đủ để build, cài, chạy

Hai công cụ này là toàn bộ năng lực của Xcode ở dạng dòng lệnh, và là thứ CI thực sự gọi. Hiểu chúng giúp bạn debug lỗi build mà giao diện chỉ hiển thị bằng một dòng đỏ.

xcodebuild -list -project EvotekNotes.xcodeproj
xcodebuild -showsdks

xcodebuild -scheme EvotekNotes -destination "id=$DEVICE" -derivedDataPath build build
xcrun simctl install "$DEVICE" build/Build/Products/Debug-iphonesimulator/EvotekNotes.app
xcrun simctl launch "$DEVICE" vn.evotek.notes
xcrun simctl io "$DEVICE" screenshot shot.png

-list cho biết target, scheme và cấu hình có thật — “scheme not found” thường chỉ là gõ sai chữ hoa. -destination nhận UDID hoặc platform=iOS Simulator,name=.... simctl launch in ra PID; nếu app thoát ngay, xem log bằng xcrun simctl spawn "$DEVICE" log stream --predicate 'process == "EvotekNotes"'.

Swift 6.4.2 toolchain và SPM

Cùng một Xcode có thể chứa nhiều toolchain, nhưng mặc định chỉ một. Kiểm tra phiên bản thật mà Terminal dùng, đừng tin vào số trong About Xcode.

swift --version
# Swift version 6.4.2
xcrun --find swift
swift package init --type library
swift build
swift test
swift package show-dependencies

Nếu swift --version ra bản khác 6.4.2 trong khi Xcode là 27.2, bạn đang có toolchain cài tay hoặc DEVELOPER_DIR trỏ bản khác trong shell hiện tại. Gỡ toolchain cài tay khỏi PATH trước khi báo lỗi lên người khác.

SPM là dependency manager mặc định; CocoaPods chỉ còn cho dự án legacy, Carthage đã chết. Từ Swift 6.4, SwiftPM build bằng Swift Build, nên cache và log nằm ở .build thay vì thư mục Xcode cũ. Một package tự viết trong repo, thêm bằng File > Add Package Dependencies hoặc khai báo trong Package.swift, rút ngắn vòng build so với build lại toàn app.

Xcode Cloud: có thì tốt, chưa cần thì bỏ qua

Xcode Cloud chạy build và test trên máy Apple, rồi đẩy bản build sang TestFlight; cần Apple Developer Program trả phí và workflow cấu hình trong App Store Connect lẫn Xcode. Với người mới, chi phí không đáng khi GitHub Actions miễn phí cho repo công khai. Chỉ bật khi bạn đã có quy trình build ổn định chạy được bằng xcodebuild trên máy local — Cloud không sửa được quy trình chưa tồn tại.

Lỗi lần mở đầu tiên và cách sửa

Triệu chứng Nguyên nhân Cách sửa
Build dừng với “No space left on device”, simulator không tạo được Đĩa đầy vì runtime, DerivedData, .xip chưa xóa df -h, xóa DerivedData, bỏ runtime cũ
Không có destination, báo runtime chưa cài Chưa tải iOS 27.2 runtime cho Xcode 27.2 xcodebuild -downloadPlatform iOS
“Signing requires a development team” Chưa thêm Apple ID hoặc chưa chọn Team Settings > Accounts, rồi chọn Team
xcodebuild dùng SDK cũ, xcrun trỏ bản cũ xcode-select trỏ Xcode cũ hoặc CLT rời xcode-select -p rồi -s đúng bản
“You have not agreed to the Xcode license agreements” License chưa accept, thường sau khi cài CLT rời sudo xcodebuild -license accept

Sáu thói quen sai nên tránh

  • Đặt beta làm Xcode mặc định. Build từ Terminal sẽ dùng SDK beta, và App Store Connect từ chối bản nộp. Giữ 27.2 làm mặc định, beta chỉ qua DEVELOPER_DIR.
  • Không accept license. Cài xong, mở Xcode, rồi bỏ qua dialog; vài tuần sau xcodebuild fail mà không rõ lý do.
  • Giữ simulator cũ. Sau vài lần nâng Xcode, danh sách destination đầy thiết bị “unavailable”, build chậm vì runtime chiếm đĩa.
  • Để project trong thư mục iCloud Drive. Desktop và Documents có thể sync lên iCloud; file provider tranh lock với Xcode, .git dễ hỏng và build chậm bất thường. Dùng ~/Developer cho code.
  • Bỏ qua dung lượng. DerivedData của vài dự án lớn chiếm hàng chục GB; cộng runtime và archive, ổ 256 GB hết nhanh.
  • Chạy song song CLT rời và Xcode đầy đủ mà không kiểm tra xcode-select -p; hai bộ SDK lệch nhau sinh lỗi “module not found” rất khó lần.

Checklist sau khi cài

  1. xcodebuild -version ra 27.2 và xcode-select -p trỏ đúng Xcode.app.
  2. swift --version ra 6.4.2 — cùng toolchain với Xcode.
  3. Đã chạy -license accept và -runFirstLaunch.
  4. Runtime iOS 27.2 đã tải, ít nhất một simulator boot được.
  5. Apple ID đã thêm, target có Team nếu chạy thiết bị thật.
  6. DerivedData có đường dẫn rõ ràng, project nằm ngoài thư mục sync iCloud.

Nhìn tới 2027

Xcode 27.3 beta sẽ thành bản ổn định trong vài tuần tới, và chu kỳ tiếp theo dự kiến mở beta iOS 28 vào giữa 2027. Mốc có deadline thật là tháng 4/2027: upload lên App Store Connect phải build bằng iOS 27 SDK và target iOS 15 trở lên. Cài 27.2 hôm nay và nâng Xcode theo bản ổn định là bạn đã tránh được phần lớn rắc rối của mốc đó.

Đọc tiếp trong series: