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

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

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

---

1. 环境配置

1.1 安装 Node.js 和 npm/yarn

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

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

1.2 安装 Java JDK（Android 必需）

Android 构建需要 JDK 17：

# macOS（Homebrew）
brew install openjdk@17# Linux（Debian/Ubuntu）
sudo apt-get install openjdk-17-jdk# Windows（手动安装）
# 下载：https://adoptium.net/temurin/releases/

验证安装：

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

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

1. 下载 Android Studio。
2. 安装时勾选：
   • Android SDK
   • Android Emulator
   • Platform Tools
3. 配置环境变量：

   # 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
   

4. 验证：

   adb --version  # 应显示版本号
   

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

1. 从 App Store 安装 Xcode。
2. 安装命令行工具：

   xcode-select --install
   sudo xcodebuild -license accept
   

---

2. 创建 React Native 项目

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

npx react-native init MyProject
cd MyProject

2.2 启动 Metro 开发服务器

npm start
# 或
yarn start

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

Metro 是什么？

1. Metro 的核心作用

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

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

2. Metro 的工作流程

3. 你与 Metro 的交互场景

• 启动 Metro：运行 npm start 时，会看到终端显示：

  Metro Bundler ready on http://localhost:8081
  

• 调试时：手机上的 JS 代码实际是通过 Metro 服务实时加载的（这就是为什么必须保持 npm start 运行）
• 报错时：Metro 会在终端和手机红屏显示错误堆栈

4. 常见 Metro 问题解决

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

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

• 问题：缓存导致代码不更新
  解决：

  npm start -- --reset-cache
  

---

总结对比表

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

---

3. 配置国内镜像加速

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

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

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

1. 修改 android/build.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()}
   }
   

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

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

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

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

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

---

4. 运行项目

4.1 运行 Android 版本

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

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

2. 编译并安装 APK：

   npx react-native run-android #另起终端运行，和metro分开
   

   • 如果首次运行，Gradle 会从国内镜像下载依赖。
   • 成功后会自动安装 APK 并启动应用。

4.2 运行 iOS 版本（仅 macOS）

1. 启动 iOS 模拟器：

   npx react-native run-ios
   

   • 会自动编译并启动模拟器。

---

5. 常见问题解决

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

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

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

问题 2：Could not resolve all dependencies

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

问题 3：Metro 无法连接设备

• 解决：

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

---