Cài đặt môi trường trên Windows

Các công cụ cần thiết để clone một dự án, cài thư viện và chạy thử. Làm theo thứ tự từ trên xuống.

1. Công cụ nền

Công cụ	Dùng để	Cách kiểm tra đã cài
Git	Quản lý mã nguồn, clone dự án	`git --version`
Node.js LTS (20 trở lên)	Chạy Expo, npm, các công cụ JavaScript	`node -v` và `npm -v`
Python 3.12+	Chạy backend FastAPI, script tự động	`python --version`
VS Code	Soạn code, chạy terminal tích hợp	Mở bằng menu Start
Docker Desktop	Chạy stack nhiều dịch vụ bằng Compose	`docker compose version`

Cài bằng winget (PowerShell)

winget install --id Git.Git -e
winget install --id OpenJS.NodeJS.LTS -e
winget install --id Python.Python.3.12 -e
winget install --id Microsoft.VisualStudioCode -e

Sau khi cài xong, đóng và mở lại terminal để PATH được cập nhật.

2. Cấu hình Git lần đầu

git config --global user.name "Tên của bạn"
git config --global user.email "[email protected]"
git config --global init.defaultBranch main

Tạo khoá SSH để làm việc với GitHub mà không cần nhập mật khẩu mỗi lần:

ssh-keygen -t ed25519 -C "[email protected]"
type %USERPROFILE%\.ssh\id_ed25519.pub

Dán nội dung file .pub vào GitHub → Settings → SSH and GPG keys.

3. Chạy một dự án

Clone repo về máy: git clone <địa-chỉ-repo> rồi cd vào thư mục vừa tạo.
Đọc README.md và CLAUDE.md (nếu có) để biết lệnh chính thức của dự án.
Cài thư viện frontend: npm install trong thư mục ứng dụng.
Tạo file biến môi trường từ file mẫu (.env.example). Không commit file .env thật.
Chạy dev server: npx expo start hoặc lệnh dev trong package.json.
Trên điện thoại, cài app Expo Go và quét mã QR trong terminal.

Backend Python (ví dụ)

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

Sau đó mở http://localhost:8000/docs để xem tài liệu API tự sinh.

4. Lỗi thường gặp

Triệu chứng	Nguyên nhân hay gặp	Cách xử lý
`npm` không được nhận diện	Node chưa có trong PATH	Cài lại Node LTS, mở lại terminal
Lỗi `ExecutionPolicy` khi chạy script .ps1	Windows chặn script	Chạy `powershell -ExecutionPolicy Bypass -File ...`
Điện thoại không kết nối được API	Điện thoại và máy tính khác mạng Wi-Fi	Dùng cùng Wi-Fi, đặt địa chỉ IP LAN của máy vào `.env`
Port đang bị chiếm	Một tiến trình khác đang chạy	Tắt tiến trình cũ hoặc đổi port