React Native 项目实战指南

快速开始（推荐）

如果你有 NDK 25 或更低版本，按照以下步骤快速搭建项目：

1. 创建项目（使用 React Native 0.72.14）

bash 复制代码

npx @react-native-community/cli init MyRNApp --version 0.72.14
cd MyRNApp

2. 配置 NDK 版本

编辑 android/build.gradle，找到 ndkVersion 并修改为你的版本：

gradle 复制代码

ndkVersion = "25.1.8937393"  // 根据你的环境修改

3. 启动项目

bash 复制代码

# 终端 1：启动 Metro Bundler
npm start

# 终端 2：运行 Android 应用
npm run android

完成！更多详细说明请继续阅读后续章节。

准备工作

⚠️ 重要提示 ：如果你的 Android 环境只有 NDK 25 或更低版本，建议使用 React Native 0.72.14 版本创建项目，以避免 NDK 版本兼容性问题。新版本的 React Native（0.73+）可能要求 NDK 27+。

环境检查清单

在开始创建项目之前，请确保以下工具已正确安装：

1. Node.js

检查是否已安装：

bash 复制代码

node --version
npm --version

如果没有安装或版本过旧（建议 16+），请访问：nodejs.org/

2. Android 环境（开发 Android 应用需要）

bash 复制代码

# 检查 Android SDK
adb --version

# 检查可用设备
adb devices

3. iOS 环境（仅 macOS，开发 iOS 应用需要）

bash 复制代码

# 检查 Xcode
xcode-select --version

# 检查可用模拟器
xcrun simctl list devices

4. 代码编辑器（推荐）

Visual Studio Code ：code.visualstudio.com/
WebStorm ：www.jetbrains.com/webstorm/

创建新项目

方式一：使用 React Native CLI（推荐原生开发）

⚠️ 重要提示 ：从 React Native 0.60+ 开始，请使用 @react-native-community/cli，而不是旧的 react-native init 命令。

步骤 1：创建项目

bash 复制代码

# 使用新的社区 CLI（推荐）
npx @react-native-community/cli init MyFirstRNApp

# 进入项目目录
cd MyFirstRNApp

如果遇到命令已弃用错误：

bash 复制代码

🚨️ The `init` command is deprecated.

请使用上面的命令替代。

步骤 2：选择项目模板和版本（推荐）

创建项目时，你可以选择不同的模板和版本：

bash 复制代码

# 创建指定版本的项目（推荐使用稳定版本，如 0.72.14）
npx @react-native-community/cli init MyFirstRNApp --version 0.72.14

# 创建 TypeScript 项目（默认已支持 TypeScript）
npx @react-native-community/cli init MyFirstRNApp --template react-native-template-typescript --version 0.72.14

💡 版本选择建议：

如果遇到 NDK 版本兼容性问题，建议使用 React Native 0.72.x 版本（兼容 NDK 23-25）

新版本可能要求 NDK 27+，如果你的环境只有 NDK 25 或更低，请使用 0.72.14

步骤 3：配置 Android NDK 版本（重要）

创建项目后，如果遇到 NDK 版本不兼容问题，需要修改 android/build.gradle 文件：

bash 复制代码

# 进入项目目录
cd MyFirstRNApp

# 编辑 android/build.gradle 文件

找到 ndkVersion 配置并修改为你环境的 NDK 版本：

gradle 复制代码

buildscript {
    ext {
        buildToolsVersion = "33.0.0"
        minSdkVersion = 21
        compileSdkVersion = 33
        targetSdkVersion = 33

        // 根据你的环境修改 NDK 版本（例如：NDK 25）
        ndkVersion = "25.1.8937393"
    }
    // ...
}

⚠️ NDK 版本说明：

NDK 25 版本号通常是 25.1.8937393

NDK 23 版本号通常是 23.1.7779620

你可以通过 Android Studio 的 SDK Manager 查看已安装的 NDK 版本

方式二：使用 Expo（推荐新手，更简单）

Expo 是一个更简单的开始方式，特别适合快速原型开发：

bash 复制代码

# 创建 Expo 项目
npx create-expo-app MyFirstRNApp

# 进入项目目录
cd MyFirstRNApp

Expo vs CLI 对比：

特性	Expo	React Native CLI
上手难度	⭐ 简单	⭐⭐ 中等
原生模块支持	受限	完全支持
项目大小	较小	较大
适合场景	快速原型、纯JS开发	需要原生功能的复杂应用

方式三：使用 Expo 带模板

bash 复制代码

# 使用 TypeScript 模板
npx create-expo-app MyFirstRNApp --template expo-template-blank-typescript

# 使用导航模板
npx create-expo-app MyFirstRNApp --template expo-template-tabs

项目结构解析

创建项目后，让我们看看项目的结构：

csharp 复制代码

MyFirstRNApp/
├── android/              # Android 原生代码目录
│   ├── app/
│   ├── build.gradle      # 构建配置（包含 NDK 版本配置）
│   └── ...
├── ios/                  # iOS 原生代码目录
│   ├── MyFirstRNApp/
│   ├── Podfile
│   └── ...
├── node_modules/         # 项目依赖包（执行 npm install 后生成）
├── __tests__/            # 测试文件目录
├── .gitignore           # Git 忽略文件配置
├── .watchmanconfig      # Watchman 配置文件
├── App.tsx 或 App.js    # 应用主组件（入口组件，0.72+ 默认使用 TypeScript）
├── app.json             # 应用配置文件
├── babel.config.js      # Babel 配置文件
├── index.js             # 应用入口文件（注册根组件）
├── metro.config.js      # Metro 打包工具配置
├── package.json         # 项目配置文件
├── package-lock.json    # 依赖版本锁定文件
├── tsconfig.json        # TypeScript 配置文件（如果使用 TypeScript）
└── README.md            # 项目说明文档

核心文件说明

`package.json`

项目的配置文件，包含：

项目依赖
脚本命令
项目元信息

json 复制代码

{
  "name": "MyFirstRNApp",
  "version": "0.0.1",
  "private": true,
  "scripts": {
    "android": "react-native run-android",
    "ios": "react-native run-ios",
    "start": "react-native start",
    "test": "jest"
  },
  "dependencies": {
    "react": "18.2.0",
    "react-native": "0.72.14"
  },
  "devDependencies": {
    "@babel/core": "^7.20.0",
    "@types/react": "^18.0.24",
    "typescript": "4.8.4"
  },
  "engines": {
    "node": ">=16"
  }
}

💡 注意：React Native 0.72.x 版本默认支持 TypeScript，如果你看到 App.tsx 而不是 App.js，这是正常的。

`index.js`

应用的入口文件，负责注册根组件：

javascript 复制代码

import {AppRegistry} from 'react-native';
import App from './App';
import {name as appName} from './app.json';

AppRegistry.registerComponent(appName, () => App);

`App.tsx` 或 `App.js`

应用的主组件，通常包含应用的主要 UI 结构。这是你主要编写代码的地方。

💡 注意：React Native 0.72+ 版本默认使用 TypeScript，所以你可能看到 App.tsx 而不是 App.js。两种格式都可以正常工作。

运行项目

启动 Metro Bundler（开发服务器）

首先，我们需要启动 Metro 打包服务器：

bash 复制代码

# 在项目根目录执行
npm start
# 或
yarn start

这将会启动一个开发服务器，用于打包和提供 JavaScript 代码。

运行 Android 应用

方法 1：使用命令行

bash 复制代码

# 确保已启动 Metro Bundler（另一个终端窗口）
npm start

# 在另一个终端窗口运行
npm run android
# 或
yarn android

方法 2：使用 Android Studio

打开 Android Studio
选择 Open，打开项目中的 android 文件夹
等待 Gradle 同步完成
点击运行按钮或按 Shift + F10

检查设备：

bash 复制代码

# 查看连接的 Android 设备
adb devices

如果没有设备，可以：

启动 Android 模拟器（Android Studio > Tools > Device Manager）
连接真机并启用 USB 调试

运行 iOS 应用（仅 macOS）

方法 1：使用命令行

bash 复制代码

# 确保已启动 Metro Bundler（另一个终端窗口）
npm start

# 在另一个终端窗口运行
npm run ios
# 或
yarn ios

方法 2：使用 Xcode

打开 ios 目录下的 .xcworkspace 文件（注意是 workspace，不是 project）
选择目标设备（模拟器或真机）
点击运行按钮或按 Cmd + R

如果是首次运行，需要安装依赖：

bash 复制代码

cd ios
pod install
cd ..

检查设备：

bash 复制代码

# 查看可用的 iOS 模拟器
xcrun simctl list devices

修改应用

现在让我们修改应用，创建一个简单的示例。

示例 1：修改 App.js

打开 App.js，让我们创建一个简单的计数器应用：

javascript 复制代码

import React, {useState} from 'react';
import {
  SafeAreaView,
  StyleSheet,
  Text,
  TouchableOpacity,
  View,
} from 'react-native';

const App = () => {
  const [count, setCount] = useState(0);

  return (
    <SafeAreaView style={styles.container}>
      <View style={styles.content}>
        <Text style={styles.title}>我的第一个 React Native 应用</Text>
        <Text style={styles.counter}>{count}</Text>
        <View style={styles.buttonContainer}>
          <TouchableOpacity
            style={[styles.button, styles.decrementButton]}
            onPress={() => setCount(count - 1)}>
            <Text style={styles.buttonText}>-</Text>
          </TouchableOpacity>
          <TouchableOpacity
            style={[styles.button, styles.incrementButton]}
            onPress={() => setCount(count + 1)}>
            <Text style={styles.buttonText}>+</Text>
          </TouchableOpacity>
        </View>
        <TouchableOpacity
          style={[styles.button, styles.resetButton]}
          onPress={() => setCount(0)}>
          <Text style={styles.buttonText}>重置</Text>
        </TouchableOpacity>
      </View>
    </SafeAreaView>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#f5f5f5',
  },
  content: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    padding: 20,
  },
  title: {
    fontSize: 24,
    fontWeight: 'bold',
    marginBottom: 30,
    color: '#333',
  },
  counter: {
    fontSize: 72,
    fontWeight: 'bold',
    color: '#007AFF',
    marginBottom: 40,
  },
  buttonContainer: {
    flexDirection: 'row',
    gap: 20,
    marginBottom: 20,
  },
  button: {
    paddingHorizontal: 30,
    paddingVertical: 15,
    borderRadius: 10,
    minWidth: 80,
    alignItems: 'center',
    justifyContent: 'center',
  },
  incrementButton: {
    backgroundColor: '#4CAF50',
  },
  decrementButton: {
    backgroundColor: '#F44336',
  },
  resetButton: {
    backgroundColor: '#FF9800',
  },
  buttonText: {
    color: '#fff',
    fontSize: 20,
    fontWeight: 'bold',
  },
});

export default App;

保存文件后，应用会自动重新加载（热重载）。

示例 2：创建自定义组件

让我们创建一个新的组件文件：

创建 src/components/Counter.js：

javascript 复制代码

import React, {useState} from 'react';
import {View, Text, TouchableOpacity, StyleSheet} from 'react-native';

const Counter = () => {
  const [count, setCount] = useState(0);

  return (
    <View style={styles.container}>
      <Text style={styles.count}>{count}</Text>
      <TouchableOpacity
        style={styles.button}
        onPress={() => setCount(count + 1)}>
        <Text style={styles.buttonText}>点击我</Text>
      </TouchableOpacity>
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    alignItems: 'center',
    margin: 20,
  },
  count: {
    fontSize: 48,
    fontWeight: 'bold',
    marginBottom: 20,
  },
  button: {
    backgroundColor: '#007AFF',
    paddingHorizontal: 30,
    paddingVertical: 15,
    borderRadius: 8,
  },
  buttonText: {
    color: '#fff',
    fontSize: 16,
    fontWeight: 'bold',
  },
});

export default Counter;

在 App.js 中使用：

javascript 复制代码

import React from 'react';
import {SafeAreaView, StyleSheet} from 'react-native';
import Counter from './src/components/Counter';

const App = () => {
  return (
    <SafeAreaView style={styles.container}>
      <Counter />
    </SafeAreaView>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
  },
});

export default App;

调试技巧

1. 使用 Chrome DevTools

启用调试模式：

Android ：在设备上按 Cmd + M（Mac）或 Ctrl + M（Windows），选择 "Debug"
iOS ：在模拟器上按 Cmd + D，选择 "Debug"

这会在 Chrome 浏览器中打开调试工具。

使用技巧：

设置断点
查看变量值
查看网络请求
查看控制台日志

2. 使用 React Native Debugger

安装独立的调试工具：

bash 复制代码

# macOS
brew install --cask react-native-debugger

# 或从 GitHub 下载
# https://github.com/jhen0409/react-native-debugger/releases

3. 使用 Flipper

Flipper 是 Meta 提供的调试工具，功能强大：

bash 复制代码

# 安装 Flipper
# 访问 https://fbflipper.com/

4. 控制台日志

在代码中使用 console.log：

javascript 复制代码

console.log('变量值：', myVariable);
console.warn('警告信息');
console.error('错误信息');

日志会显示在：

Metro Bundler 终端窗口
Chrome DevTools 控制台
React Native Debugger

5. 错误提示

React Native 提供了友好的错误提示界面（红屏错误），会显示：

错误堆栈信息
错误发生的位置
修复建议

常见问题解决

问题 1：`react-native init` 命令已弃用

错误信息：

csharp 复制代码

🚨️ The `init` command is deprecated.

解决方案：

bash 复制代码

# 使用新的命令
npx @react-native-community/cli init MyApp

问题 2：Metro Bundler 端口被占用

错误信息：

perl 复制代码

Error: listen EADDRINUSE: address already in use :::8081

解决方案：

bash 复制代码

# 查找占用端口的进程
lsof -i :8081

# 结束进程（替换 PID 为实际进程ID）
kill -9 <PID>

# 或使用指定端口启动
npm start -- --port 8082

问题 3：Android 构建失败 - NDK 版本不兼容

错误信息示例：

arduino 复制代码

NDK version not found
Could not find NDK version XX

解决方案：

检查已安装的 NDK 版本

bash 复制代码

# 在 Android Studio 中：Tools > SDK Manager > SDK Tools > 勾选 Show Package Details
# 查看已安装的 NDK 版本号

修改项目 NDK 版本配置

编辑 android/build.gradle 文件，修改 ndkVersion：

gradle 复制代码

buildscript {
    ext {
        buildToolsVersion = "33.0.0"
        minSdkVersion = 21
        compileSdkVersion = 33
        targetSdkVersion = 33

        // 根据你的环境修改为已安装的 NDK 版本
        // NDK 25: "25.1.8937393"
        // NDK 23: "23.1.7779620"
        ndkVersion = "25.1.8937393"
    }
}

如果 NDK 未安装，安装指定版本

打开 Android Studio
Tools > SDK Manager > SDK Tools
勾选 "Show Package Details"
展开 "NDK (Side by side)"
选择并安装你需要的 NDK 版本（如 25.1.8937393）

其他构建失败的解决方案

bash 复制代码

# 清理构建缓存
cd android
./gradlew clean
cd ..

# 重新安装依赖
rm -rf node_modules
npm install

# 清理 Metro 缓存
npm start -- --reset-cache

问题 4：iOS pod install 失败

解决方案：

bash 复制代码

# 更新 CocoaPods
sudo gem install cocoapods

# 清理并重新安装
cd ios
rm -rf Pods Podfile.lock
pod cache clean --all
pod install
cd ..

问题 5：找不到设备

Android：

bash 复制代码

# 检查设备连接
adb devices

# 如果没有设备，确保：
# 1. USB 调试已启用
# 2. 已安装设备驱动
# 3. 模拟器已启动

iOS：

bash 复制代码

# 查看可用模拟器
xcrun simctl list devices

# 启动特定模拟器
xcrun simctl boot "iPhone 14"

# 或从 Xcode 启动

问题 6：依赖安装失败

解决方案：

bash 复制代码

# 清理缓存
npm cache clean --force
# 或
yarn cache clean

# 删除 node_modules 和锁定文件
rm -rf node_modules package-lock.json yarn.lock

# 重新安装
npm install
# 或
yarn install

问题 7：热重载不工作

解决方案：

bash 复制代码

# 重启 Metro Bundler
# 按 Ctrl + C 停止，然后重新运行
npm start -- --reset-cache

# 在应用中：
# Android: 按 R + R
# iOS: 按 Cmd + R

问题 8：NDK 版本与 React Native 版本不匹配

问题描述：

新版本的 React Native（0.73+）可能要求 NDK 27 或更高版本，但你的环境只有 NDK 25 或更低。

解决方案：

使用兼容的 React Native 版本

推荐使用 React Native 0.72.14，它与 NDK 23-25 兼容：

bash 复制代码

# 创建项目时指定版本
npx @react-native-community/cli init MyApp --version 0.72.14

配置项目使用指定的 NDK 版本

修改 android/build.gradle 中的 ndkVersion 为你的环境版本：

gradle 复制代码

ndkVersion = "25.1.8937393"  // 或你已安装的其他版本

验证配置

bash 复制代码

# 进入项目目录
cd MyApp

# 清理并重新构建
cd android
./gradlew clean
cd ..
npm run android

下一步

现在你已经成功创建并运行了一个 React Native 项目！接下来可以：

📖 学习 React Native 基础
- 组件（View, Text, Image, ScrollView 等）
- 样式（StyleSheet）
- 导航（React Navigation）
🔄 学习状态管理
- useState, useEffect
- Context API
- Redux 或 Zustand
🎨 学习 UI 库
- React Native Elements
- NativeBase
- React Native Paper
📱 学习平台特定功能
- 访问相机
- 地理位置
- 推送通知
🧪 学习测试
- Jest 单元测试
- React Native Testing Library

推荐学习资源：

祝您开发愉快！🚀

React Native 项目实战指南