Skip to content
环境准备与工具链
React Native 开发需要一组本地工具协同工作：Node.js 负责包管理和 Metro 打包，JDK 提供 Android 构建所需的 Java 运行时，Android Studio 管理 Android SDK 与模拟器，Xcode 管理 iOS 编译链与模拟器。这几者组合在一起就是开发环境的工具链——链条上每个环节都可能成为问题点，越少的环节意味着越少的潜在故障[1]。搭建时尽量保持软件版本匹配，避免引入不必要的差异。
安装 Node.js 与 JDK
Node.js 版本需要 14 或以上。执行 node -v 查看当前版本，若未安装，从官网下载 LTS 版安装。
JDK 是 Android 构建的必要组件。推荐 JDK 11。较新的 JDK（如 17 及以上）在 React Native 的某些构建步骤中可能引发兼容问题[3]。用 java -version 检查当前版本，如果不是 11，可通过 Homebrew（macOS）或直接下载 OpenJDK 11 安装。
bash
# 检查版本
$ node -v
v18.16.0
$ java -version
openjdk version "11.0.20" 2023-07-18 LTS注意点
如果系统中已安装了高版本 JDK（如 Java 17），可保留，但需设置JAVA_HOME环境变量指向 JDK 11。Android Gradle 插件在读取JAVA_HOME时会使用该版本。macOS 下可通过/usr/libexec/java_home -v 11查看路径。
配置 Android Studio 与 SDK
安装 Android Studio 时需确认以下组件已勾选：
- Android SDK
- Android SDK Platform（通常选最新稳定版）
- Android Virtual Device (AVD)
如果机器未启用 Hyper-V（Windows 下常见），还需勾选 Intel HAXM（Intel Hardware Accelerated Execution Manager），它能让模拟器运行更流畅。AMD CPU 则需要使用系统的虚拟化方案。
安装完成后，打开 SDK Manager（Welcome 界面或 Tools 菜单），检查“SDK Platforms”下是否至少有一个 Android 版本（例如 API 33 / Android 13），并在“SDK Tools”里确认以下工具已安装：
- Android SDK Build-Tools
- Android Emulator
- Android SDK Platform-Tools
- Intel HAXM（仅 Intel CPU）
环境变量方面，Android Studio 通常会自行配置 ANDROID_SDK_ROOT，若未生效，需在系统环境变量或 shell 配置文件中手动设置。可用 echo $ANDROID_SDK_ROOT 检查。
配置 Xcode 与 CocoaPods
macOS 上需要 Xcode（尽量选择与当前 macOS 兼容的最新稳定版）。先安装命令行工具：
bash
xcode-select --install之后使用 Ruby 自带的 gem 安装 CocoaPods：
bash
sudo gem install cocoapods若网络下载慢，可更换 gem 源或改用 Homebrew 安装：
bash
brew install cocoapods安装完成后运行 pod --version 确认可用。
CocoaPods 在每次修改过原生依赖（例如添加新的原生模块）后，需要在 ios/ 目录里执行 pod install 来同步依赖。项目模板已包含一份 Podfile，首次运行 iOS 构建时，React Native CLI 会自动执行 pod install。若遇到问题，通常需要手动进入 ios 目录再跑一遍 pod install。
创建第一个 React Native 项目
使用 React Native CLI 初始化
React Native CLI 是官方项目模板的脚手架。无需全局安装 react-native 命令，直接通过 npx 运行：
bash
npx react-native init MyFirstAppnpx 会临时下载对应的 CLI 版本，保证使用的是当前最新模板，避免全局版本过时的问题。默认创建的是 TypeScript 项目（模板里带有 tsconfig.json 和 .tsx 后缀的入口文件）。
初始化过程会下载模板文件、安装 JavaScript 依赖（约数百个包），可能需要几分钟。完成后 MyFirstApp 目录下包含完整的项目骨架。
进入项目目录：
bash
cd MyFirstApp查看 package.json，其中定义了 scripts：
android→react-native run-androidios→react-native run-iosstart→react-native start
使用 Expo 创建项目（可选）
如果暂时不需接触原生工程（不修改原生代码），Expo 提供了更轻量的启动方式。同样通过 npx 执行：
bash
npx create-expo-app MyExpoApp该命令产生的项目没有 android/ 和 ios/ 目录，开发时通过 Expo Go 应用在真机或模拟器上预览。Expo 适合快速原型或纯 JavaScript 开发。若后期需要用到原生模块，可通过 expo prebuild 生成原生工程。本篇后续步骤主要围绕 React Native CLI 项目展开。
启动 Metro 开发服务器
Metro 是 React Native 的 JavaScript 打包器，主要职责：
- 启动本地开发服务器（默认端口 8081）
- 将 JS/TS 源码实时编译为单个 JS Bundle
- 提供增量编译和 Fast Refresh（保存代码后即时刷新界面）
在项目根目录运行：
bash
npx react-native start等价于 npm start。终端输出类似：
▒▒▓▓▓▓▒▒
▒▓▓▓▒▒░░▒▒▓▓▓▓▓
▒▓▓░░ ░▒▓▓▓▓▓
▓▓▒░ ░▒▓▓▓▓▓▓▓
▒▓▒ ░▒▓▓▓▓▓▓▓▓▓
▒▓ ░▓▓▓▓▓▓▓▓▓▓▓
▓▓░▓▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓▓▓▓▓▓▓▓ ███ █████
▓▓▓▓▓▓▓▓▓▓▓▓ ██ █ ████
▓▓▓▓▓▓▓▓▓▓▓▓ ██▄▄██ ██▄▄
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ██████
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ██ ███
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ██ ███
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ███ ███
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
Welcome to Metro v0.76.7
Fast - Scalable - Integrated服务启动后开始监听 8081 端口。访问 http://localhost:8081 可看到 Metro 的简易界面。
Metro 的实时刷新依赖该服务：当模拟器或真机上的应用加载 JS Bundle 时，会通过 WebSocket 与 Metro 建立连接，文件变动后 Metro 推送增量更新，应用局部热替换组件（Fast Refresh），无需完整重新加载。
若需修改端口，使用 --port 参数，例如 --port 8088，同时在运行应用的命令中同步指定该端口。
在模拟器中运行应用
保持 Metro 服务运行，并分别在 Android 和 iOS 模拟器里启动应用。
Android 模拟器运行步骤
- 确保有一个可用的 Android 虚拟设备。在 Android Studio 中打开 AVD Manager，创建一个设备（例如 Pixel 4，系统镜像用 API 33 且带有 Google APIs），启动该虚拟设备直至主屏幕。
- 在项目根目录新开一个终端，运行：
bash
npx react-native run-android该命令会：
- 读取
android/工程 - 调用 Gradle 编译原生代码（首次会下载依赖，耗时较长）
- 安装 APK 到已连接的模拟器
- 启动应用，应用会自动连接 Metro 服务获取 JS Bundle
终端输出片段：
info Installing the app...
> Task :app:installDebug
Installing APK 'app-debug.apk' on 'Pixel_4_API_33(AVD)'
Installed on 1 device.应用启动后，模拟器上应能看到 React Native 的默认欢迎界面。
- 修改代码验证 Fast Refresh：打开项目里的
App.tsx，找到<Text>中的默认文字，改成其他内容并保存。模拟器上的界面应立刻更新。若无反应，可按菜单键（或双击 R）手动触发重载；真机上通常是摇晃设备调出 Dev Menu。
iOS 模拟器运行步骤
仅限 macOS。
- 确认 Xcode 已安装命令行工具，且至少有一个模拟器可用（系统自带）。
- 在项目根目录运行：
bash
npx react-native run-ios首次执行时，它会自动进入 ios/ 目录执行 pod install，安装 CocoaPods 依赖。成功后自动启动模拟器（默认选用某个型号，如 iPhone 14），然后编译、安装并启动应用。
若想指定模拟器型号，加 --simulator 参数：
bash
npx react-native run-ios --simulator="iPhone 15"应用启动后，同样可通过修改 App.tsx 观察界面变化。iOS 模拟器的 Fast Refresh 行为与 Android 基本一致。
修改 App 入口文件展示初始界面
入口文件是 index.js（或 index.ts）：
js
import {AppRegistry} from 'react-native';
import App from './App';
import {name as appName} from './app.json';
AppRegistry.registerComponent(appName, () => App);它只做一件事：将根组件 App 注册为整个应用的入口。实际界面由 App.tsx 决定。修改初始界面的方式就是修改 App.tsx：
tsx
import React from 'react';
import {View, Text, StyleSheet} from 'react-native';
const App = () => {
return (
<View style={styles.container}>
<Text style={styles.welcome}>My First App</Text>
</View>
);
};
const styles = StyleSheet.create({
container: {
flex: 1,
justifyContent: 'center',
alignItems: 'center',
},
welcome: {
fontSize: 24,
fontWeight: '600',
},
});
export default App;保存后模拟器热更新，默认文字由 “Welcome to React Native” 变为 “My First App”。
<View>、<Text> 和 StyleSheet 将在下一篇详细展开。在本篇中，只需要知道修改 App.tsx 即可控制模拟器上的显示内容。
项目目录与关键文件说明
React Native CLI 生成的目录结构：
MyFirstApp/
├── android/ # Android 原生工程（可用 Android Studio 打开）
├── ios/ # iOS 原生工程（可用 Xcode 打开）
├── App.tsx # 根组件
├── index.js # 入口，注册 App 组件
├── package.json # 依赖与脚本
├── tsconfig.json # TypeScript 配置
├── babel.config.js # Babel 配置
├── metro.config.js # Metro 打包器配置
├── .watchmanconfig # Watchman 文件监视配置
└── ...android/和ios/：原生工程目录，包含所有原生平台代码和配置。当需要修改原生端能力（如添加权限、集成第三方原生 SDK）时在这里操作。仅修改 JavaScript 代码无须关注。App.tsx：应用根组件，启动后看到的界面来自这里，也是开发时改动最频繁的文件。index.js：React Native 应用的入口点，内容固定，负责把App组件注册到原生端。若需调整入口逻辑（如引入全局上下文 Provider），可在此文件修改。package.json：列出 JavaScript 依赖和脚本。react-native是核心依赖，react是必须的对等依赖。scripts里的命令已在前文使用。metro.config.js：Metro 的配置。如要支持额外文件类型或配置别名路径，可在此调整。默认模板通常无需改动。babel.config.js：Babel 的配置。React Native 的 Metro 默认使用 Babel 转译代码，该文件预设了module:metro-react-native-babel-preset，一般情况下也无须更改。.watchmanconfig：Watchman 是 Facebook 开发的文件监视服务，Metro 用它监听文件变化，实现快速增量编译。该文件可留空，仅需表明存在。
常见环境问题与排查思路
即便按照文档操作，环境搭建过程仍可能遇到问题。以下列出几类频率较高的情形及定位方向。
Metro 端口被占用
启动 Metro 时提示 Error: listen EADDRINUSE: address already in use :::8081，说明 8081 端口已被其他程序占用。排查方式：
bash
# 找出占用进程
lsof -i :8081或者使用 npx kill-port 8081（需先安装 kill-port）。杀掉占用进程后重新运行 npx react-native start。
Android 模拟器启动失败 / 黑屏
常见原因：
- 未安装 HAXM 或与 Hyper-V 冲突。在 SDK Tools 里确认 Intel HAXM 已安装。Windows 下如果开启了 Hyper-V，需关闭 Hyper-V 或改用 WHPX（Windows Hypervisor Platform）加速。部分 BIOS 设置也需要开启 VT-x。
- AVD 系统镜像损坏。在 AVD Manager 里删除设备重新创建，选择其他版本的系统镜像。
run-android 时 Gradle 下载依赖失败
国内网络环境下，Gradle 或 Maven 仓库连接可能超时。可替换为镜像源（修改 android/build.gradle 中的仓库地址）。首次运行 run-android 会下载 Gradle wrapper，若下载过慢，可手动下载后放到 ~/.gradle/wrapper/dists/ 目录。
iOS 构建失败 / CocoaPods 错误
多出现在首次 run-ios 或手动执行 pod install 时。尝试：
bash
cd ios
pod repo update
pod install如果仍失败，删除 ios/Pods/ 目录和 ios/Podfile.lock 后重新执行 pod install。CocoaPods 版本过低也可能导致问题，升级到最新稳定版（sudo gem update cocoapods）。
Java 版本过高
Android 编译时报出 Unsupported class file major version 61 之类的错误，说明使用了 JDK 17 编译，而 Gradle 期望 JDK 11 的类版本。确认 JAVA_HOME 指向 JDK 11，并在 Android Studio 的 Project Structure 中检查 JDK 位置。
诊断命令
React Native CLI 从 0.64 开始内置了 doctor 命令，可用于检查环境问题：
bash
npx react-native doctor它会列出环境就绪状态及缺失组件。大多数基础问题可从此处获得线索。