React Native 从零开始完整教程（环境配置 → 国内镜像加速 → 运行项目）

本教程将从 环境配置 开始，到 国内镜像加速，最后成功运行 React Native 项目（Android/iOS），适合新手和遇到网络问题的开发者。

1. 环境配置

1.1 安装 Node.js 和 npm/yarn

React Native 需要 Node.js（建议 LTS 版本）：

bash 复制代码

# 安装 Node.js（官网：https://nodejs.org/）
# 安装后检查版本
node -v  # 要求 >= 16
npm -v   # 或 yarn -v（推荐 yarn）

1.2 安装 Java JDK（Android 必需）

Android 构建需要 JDK 17：

bash 复制代码

# macOS（Homebrew）
brew install openjdk@17

# Linux（Debian/Ubuntu）
sudo apt-get install openjdk-17-jdk

# Windows（手动安装）
# 下载：https://adoptium.net/temurin/releases/

验证安装：

bash 复制代码

java -version  # 应显示 "openjdk 17.x.x"

1.3 安装 Android Studio（Android 开发环境）

下载 Android Studio。
安装时勾选：
- Android SDK
- Android Emulator
- Platform Tools

配置环境变量：

bash 复制代码

# macOS/Linux：添加到 ~/.zshrc 或 ~/.bashrc
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/platform-tools
export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin

# Windows：在系统环境变量中添加 ANDROID_HOME 和 Path
 右键 此电脑 → 属性 → 高级系统设置 → 环境变量
 在 系统变量 中：
 1. 新建变量名 ANDROID_HOME，值为 SDK 路径
 （如 C:\Users\你的用户名\AppData\Local\Android\Sdk）
 2. 编辑 PATH，添加两条新值：
 %ANDROID_HOME%\platform-tools
 %ANDROID_HOME%\emulator

验证：
bash 复制代码
```
adb --version  # 应显示版本号
```

1.4 安装 Xcode（仅 macOS，iOS 开发）

从 App Store 安装 Xcode。

安装命令行工具：

bash 复制代码

xcode-select --install
sudo xcodebuild -license accept

2. 创建 React Native 项目

2.1 使用官方模板初始化项目

bash 复制代码

npx @react-native-community/cli init MyProject
cd MyProject

2.2 启动 Metro 开发服务器

bash 复制代码

npm start
# 或
yarn start

Metro 会启动一个本地服务（默认端口 8081），提供 JavaScript 代码的热更新。

Metro 是什么？

1. Metro 的核心作用

Metro 是 React Native 专用的 JavaScript 打包工具，负责：

实时将你的 React 代码和依赖打包成单个 .bundle 文件
支持开发时的热更新（Hot Reloading）
提供错误提示和日志（终端中显示的红色错误框就是它的功劳）

2. Metro 的工作流程

graph LR A[你的代码] --> B(Metro 打包器) B --> C{开发模式?} C -->|是| D[生成可调试的 bundle] C -->|否| E[生成优化的生产包] D --> F[发送到手机/模拟器]

3. 你与 Metro 的交互场景

启动 Metro ：运行 npm start 时，会看到终端显示：
bash 复制代码
```
Metro Bundler ready on http://localhost:8081
```
调试时 ：手机上的 JS 代码实际是通过 Metro 服务实时加载的（这就是为什么必须保持 npm start 运行）
报错时：Metro 会在终端和手机红屏显示错误堆栈

4. 常见 Metro 问题解决

问题：Metro 无法启动（端口占用）
解决：

bash 复制代码

lsof -i :8081    # 查看占用进程
kill -9 <PID>    # 强制结束进程

问题：缓存导致代码不更新
解决：
bash 复制代码
```
npm start -- --reset-cache
```

总结对比表

概念	作用	是否需要手动配置
环境变量	告诉系统 Android 工具在哪	✔️ 必须配置
Metro	打包和运行 JS 代码	❌ 自动集成于 RN 项目

3. 配置国内镜像加速

3.1 配置 npm/yarn 镜像（加速 JS 依赖下载）

bash 复制代码

# 使用淘宝镜像
npm config set registry https://registry.npmmirror.com
# 或
yarn config set registry https://registry.npmmirror.com

3.2 配置 Gradle 镜像（加速 Android 依赖下载）

修改 android/build.gradle：

gradle 复制代码

allprojects {
    repositories {
        // 阿里云镜像（优先）
        maven { url 'https://maven.aliyun.com/repository/public' }
        maven { url 'https://maven.aliyun.com/repository/google' }
        // 腾讯云镜像（备用）
        maven { url 'https://mirrors.cloud.tencent.com/nexus/repository/maven-public/' }
        // 默认仓库（确保兼容性）
        google()
        mavenCentral()
    }
}

修改 android/gradle/wrapper/gradle-wrapper.properties：

properties 复制代码

# 替换为腾讯云镜像
distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-8.13-bin.zip

3.3 配置 Maven 镜像（加速 Android 原生库下载）

在 android/build.gradle 的 buildscript 中添加：

gradle 复制代码

buildscript {
    repositories {
        maven { url 'https://maven.aliyun.com/repository/public' }
        maven { url 'https://maven.aliyun.com/repository/google' }
        google()
        mavenCentral()
    }
}

4. 运行项目

4.1 运行 Android 版本

启动 Android 模拟器（通过 Android Studio 或命令行）：

bash 复制代码

emulator -list-avds  # 列出可用模拟器
emulator -avd Pixel_5_API_34  # 启动模拟器

编译并安装 APK：
bash 复制代码
```
npx react-native run-android #另起终端运行，和metro分开
```
- 如果首次运行，Gradle 会从国内镜像下载依赖。
- 成功后会自动安装 APK 并启动应用。

4.2 运行 iOS 版本（仅 macOS）

启动 iOS 模拟器：
bash 复制代码
```
npx react-native run-ios
```
- 会自动编译并启动模拟器。

5. 常见问题解决

问题 1：Gradle 下载卡住或超时

原因：网络问题或缓存冲突。

解决：

bash 复制代码

cd android
./gradlew clean  # 清理构建缓存
rm -rf ~/.gradle/caches/  # 删除全局缓存

问题 2：`Could not resolve all dependencies`

原因：某些库不在镜像中。
解决：在 build.gradle 中保留 google() 和 mavenCentral()。

问题 3：Metro 无法连接设备

解决：

bash 复制代码

adb reverse tcp:8081 tcp:8081  # 确保设备能访问 Metro

React Native 从零开始完整教程（环境配置 → 国内镜像加速 → 运行项目）