Cài Flutter SDK và flutter doctor

Trong 10 ngày tới, bạn sẽ đi từ số 0 đến một app Flutter có kiến trúc, chạy trên máy thật, cùng một codebase cho cả Android lẫn iOS. Ngày đầu chỉ có một mục tiêu, và nó đo được bằng một lệnh: flutter doctor báo xanh.

Setup là ngày nhiều người bỏ cuộc nhất. Bài này đi chậm và xử lý sẵn các bẫy phổ biến để bạn làm đúng một lần rồi thôi.

Yêu Cầu Máy

Build app iOS cần macOS. Dùng Windows/Linux bạn vẫn học được 100% khóa này với Android; code bạn viết chạy được trên iOS khi có máy Mac (hoặc dịch vụ build đám mây) sau này.

Phần 1: Cài Flutter SDK

Khóa dùng bản Flutter mới nhất trên kênh stable. Bạn cài từ repo chính thức của Flutter trên GitHub, bằng cách clone nhánh stable. Chọn một trong hai cách: tự gõ từng lệnh (Cách 1), hoặc giao việc gõ lệnh cho AI coding agent và tự duyệt từng lệnh nó chạy (Cách 2).

Chuẩn bị

Gõ git --version. Có số in ra là được. Chưa có git thì cài trước:

Cài xong, mở terminal mới và gõ lại git --version.

Lần chạy đầu Flutter tải thêm Dart SDK và các công cụ đi kèm, nên thư mục flutter sẽ nặng hơn 1 GB. Nên dùng mạng ổn định.

Cách 1: Tự Cài Từng Bước

Bước 1: clone nhánh stable vào thư mục development trong thư mục người dùng, chỗ không cần quyền admin. Nếu ở đó đã có thư mục flutter từ lần cài trước, đổi tên nó đi trước.

# macOS, Linux
mkdir -p ~/development && cd ~/development
git clone https://github.com/flutter/flutter.git -b stable

# Windows (PowerShell, không cần Run as administrator)
New-Item -ItemType Directory -Force -Path $HOME\development | Out-Null
Set-Location $HOME\development
git clone https://github.com/flutter/flutter.git -b stable

Nhớ giữ -b stable. Thiếu nó, bạn lấy nhánh master đang phát triển.

Bước 2: thêm flutter/bin vào PATH. Quên bước này là nguồn của lỗi flutter: command not found. Chọn đúng một dòng theo máy của bạn:

# macOS (zsh là shell mặc định)
echo 'export PATH="$HOME/development/flutter/bin:$PATH"' >> ~/.zprofile

# Linux dùng bash
echo 'export PATH="$HOME/development/flutter/bin:$PATH"' >> ~/.bashrc

# Linux dùng zsh
echo 'export PATH="$HOME/development/flutter/bin:$PATH"' >> ~/.zshenv

Trên Windows, hai dòng đầu thêm flutter\bin vào đầu PATH của tài khoản bạn (PATH hệ thống giữ nguyên), dòng thứ ba in PATH đó ra để bạn kiểm:

$userPath = [Environment]::GetEnvironmentVariable('Path', 'User')
[Environment]::SetEnvironmentVariable('Path', "$HOME\development\flutter\bin;$userPath", 'User')
[Environment]::GetEnvironmentVariable('Path', 'User')

Bước 3: kiểm tra. PATH mới chỉ có hiệu lực ở cửa sổ mở sau đó. Đóng terminal, mở cái mới (trên Windows thì đóng luôn VS Code nếu đang mở), rồi chạy:

flutter --version

Lần đầu lệnh này chạy khá lâu vì phải tải Dart SDK. Xong, dòng đầu có dạng Flutter 3.x.y • channel stable • https://github.com/flutter/flutter.git. Số bản tùy lúc bạn cài, chỉ cần thấy chữ channel stable. Không tìm thấy lệnh hoặc báo kênh khác thì chạy which flutter (macOS, Linux) hoặc where.exe flutter (Windows). Đường dẫn in ra phải nằm trong development/flutter/bin (Windows: development\flutter\bin), nếu không thì xóa dòng PATH của bản cũ.

Cuối cùng chạy flutter doctor. Lúc này chỉ cần dòng đầu là [✓] Flutter (Channel stable, ...). Android toolchain hay Xcode báo ✗ hoặc ! là bình thường vì bạn chưa cài chúng, Phần 2 sẽ xử lý.

Về sau muốn lên bản stable mới hơn, chạy flutter upgrade.

Cách 2: Giao Cho AI Coding Agent

Dùng cách này khi máy bạn đã có AI coding agent chạy được lệnh trong terminal (Cursor, Claude Code, Codex...). Chưa có thì làm Cách 1. Bấm nút Giao cho AI Coding Agent trên thanh công cụ của bài để copy prompt, mở agent ở một thư mục bất kỳ rồi dán vào. Prompt giao đúng việc của Cách 1, kèm vài giới hạn an toàn: không dùng sudo hay quyền administrator, không chạy script tải từ mạng qua pipe, không xoá gì, và chỉ sửa PATH của tài khoản bạn.

Agent gõ lệnh, còn việc duyệt vẫn là của bạn. Đọc kế hoạch trước khi trả lời "yes", và đọc từng lệnh agent xin chạy trước khi bấm cho phép, nhất là lệnh có sudo, rm hay lệnh ghi vào file shell và PATH. Agent clone từ URL khác https://github.com/flutter/flutter.git hoặc thiếu -b stable thì từ chối và hỏi lại. Lệnh nào chưa hiểu thì bảo agent giải thích trước. Trong báo cáo cuối, mọi file bị sửa phải nằm trong kế hoạch bạn đã duyệt.

Agent báo xong thì tự mở terminal mới và chạy flutter --version như Bước 3. Agent chạy trong cửa sổ riêng, nên có thể báo thành công khi terminal của bạn chưa nhận PATH.

Phần 2: flutter doctor, Bác Sĩ Toàn Khoa

flutter doctor

Lệnh này khám tổng quát máy bạn và in ra từng hạng mục. Output điển hình lần đầu:

[✓] Flutter (Channel stable, 3.x.y, ...)
[✗] Android toolchain - develop for Android devices
    ✗ Unable to locate Android SDK.
      Install Android Studio from: https://developer.android.com/studio/index.html
      On first launch it will assist you in installing the Android SDK components.
[✓] Chrome - develop for the web
[✗] Xcode - develop for iOS and macOS
[✓] Connected device (2 available)
[✓] Network resources

Dòng Xcode chỉ hiện trên macOS.

Cách đọc: ✓ là ổn, ! là thiếu một phần, ✗ là chưa có. Không cần xanh hết mọi dòng. Bạn chỉ cần xanh các dòng phục vụ mục tiêu của khóa:

Trên Windows và Linux có thể có thêm dòng Visual Studio hoặc Linux toolchain. Hai dòng này chỉ dùng để build app desktop, khóa không cần, bỏ qua.

Với Android toolchain: cài Android Studio từ developer.android.com/studio (Flutter dùng SDK và emulator của nó, kể cả khi bạn code bằng VS Code). Mở Android Studio lần đầu và để nó cài Android SDK, rồi chạy lại flutter doctor. Lúc này dòng Android toolchain thường chuyển sang [!], kèm việc còn thiếu. Hay gặp nhất là cmdline-tools component is missing: mở SDK Manager, tab SDK Tools, tích Android SDK Command-line Tools, bấm Apply. Sau đó chấp nhận license:

flutter doctor --android-licenses

Gõ y chấp nhận hết. Chạy lại flutter doctor sau mỗi lần sửa để xem tiến triển.

Phần 3: Nơi Chạy App

Chọn ít nhất một, máy thật luôn là lựa chọn tốt nhất nếu có:

Máy Android thật

1. Settings → About phone, nhấn 7 lần vào Build number để mở Developer options.
2. Bật USB debugging trong Settings → System → Developer options.
3. Cắm cáp, chọn Allow khi điện thoại hỏi.

Emulator Android

Mở Android Studio → Device Manager → Create Virtual Device → chọn Pixel 8 + system image mới nhất có chữ Recommended → Finish → nhấn Play.

iPhone / Simulator (chỉ macOS)

• Simulator: open -a Simulator sau khi cài Xcode.
• iPhone thật: cần cáp và bật Developer Mode trong Settings của máy. Xcode sẽ hướng dẫn phần này khi bạn chạy lần đầu ở bài sau.

Phần 4: Kiểm Tra Cuối

flutter devices

Cần thấy ít nhất một device trong danh sách. Nếu trống: emulator chưa khởi động xong, hoặc máy thật chưa Allow USB debugging, hoặc cáp chỉ sạc không truyền data, thử cáp khác.

Phần khó nhất của khóa đã xong. Bài sau: tạo project đầu tiên và gặp tính năng khiến Flutter nổi tiếng, hot reload.