Hướng dẫn cài đặt môi trường cho dự án React Native

React Native có hai lộ trình cài đặt phổ biến: bắt đầu nhanh với Expo hoặc chuẩn bị đầy đủ native toolchain để tự build Android/iOS. Chọn đúng lộ trình ngay từ đầu giúp tránh cài hàng chục GB công cụ không cần thiết.

Chọn Expo hay native toolchain?

Cài Node.js LTS và công cụ cơ bản

Nên dùng trình quản lý phiên bản như nvm, fnm hoặc Volta để mỗi dự án có phiên bản Node phù hợp.

node --version
npm --version
git --version

Không cài React Native CLI toàn cục; dùng npx để lấy CLI phù hợp với dự án.

Lộ trình Expo

npx create-expo-app@latest my-mobile-app
cd my-mobile-app
npx expo start

Quét QR bằng thiết bị cùng mạng, hoặc nhấn a/i để mở Android Emulator/iOS Simulator. Khi mạng nội bộ chặn kết nối, thử npx expo start --tunnel.

Chuẩn bị Android native

1. Cài Android Studio và Android SDK theo tài liệu React Native.
2. Trong SDK Manager, cài platform, build-tools, platform-tools và emulator tương thích với dự án.
3. Tạo Android Virtual Device trong Device Manager.
4. Cấu hình ANDROID_HOME và thêm platform-tools vào PATH.
5. Cài JDK theo phiên bản React Native đang dùng; không đoán phiên bản từ hướng dẫn cũ.

adb --version
adb devices
java -version
npx react-native doctor

Chuẩn bị iOS trên macOS

Build iOS local yêu cầu macOS và Xcode. Sau khi cài Xcode, mở một lần để chấp nhận license và tải component cần thiết. Cài CocoaPods nếu dự án yêu cầu, rồi cài pods:

xcode-select -p
sudo gem install cocoapods
cd ios && pod install && cd ..

Với máy quản lý Ruby bằng Bundler, ưu tiên bundle exec pod install để đồng nhất phiên bản CocoaPods.

Tạo dự án không dùng Expo

npx @react-native-community/cli@latest init MyApp
cd MyApp
npm start
npm run android
npm run ios

Kiểm tra tài liệu phiên bản React Native của dự án vì yêu cầu Node, JDK, Gradle, Xcode và CocoaPods thay đổi theo thời gian.

Kết nối thiết bị thật

• Android: bật Developer options và USB debugging, xác nhận thiết bị bằng adb devices.
• iOS: chọn Development Team trong Xcode và tin cậy chứng chỉ trên thiết bị.
• Đảm bảo máy và thiết bị truy cập được Metro bundler; firewall/VPN có thể chặn cổng phát triển.

Biến môi trường và dữ liệu nhạy cảm

Expo tự nạp biến có tiền tố EXPO_PUBLIC_ vào mã client. Bất kỳ giá trị nào nằm trong bundle mobile đều có thể bị đọc, vì vậy không đặt private API key hoặc secret backend trong ứng dụng.

Lỗi thường gặp

• SDK location not found: kiểm tra ANDROID_HOME và local.properties.
• Không thấy thiết bị: kiểm tra cáp, quyền USB debugging và adb kill-server/adb start-server.
• Pod lỗi: xóa cache có chọn lọc, cập nhật repo khi cần và giữ phiên bản bằng Gemfile.
• Metro cache cũ: dùng npx react-native start --reset-cache hoặc tùy chọn tương ứng của Expo.

Checklist hoàn tất

1. Dự án cài dependency từ lock file thành công.
2. Metro khởi động và ứng dụng mở trên ít nhất một emulator hoặc thiết bị thật.
3. react-native doctor không còn lỗi bắt buộc.
4. Phiên bản Node/JDK được ghi trong README hoặc file quản lý phiên bản.
5. Không có secret trong mã client hay repository.

Nguồn tham khảo

• React Native environment setup
• Create an Expo project