bestprize的编程技术分享小站

专注前端与移动端技术分享

React Native最简教程

欢迎使用 React Native！这篇文档会帮助你搭建基本的 React Native 开发环境。

快速开始方式
React Native CLI Expo Go
开发平台
macOS Windows Linux
目标平台
Android iOS

根据你所使用的操作系统、针对的目标平台不同，具体步骤有所不同。如果想同时开发 iOS 和 Android 也没问题，你只需要先选一个平台开始，另一个平台的环境搭建只是稍有不同。

如果 阅读完本文档 后还碰到很多环境搭建的问题，我们建议你还可以再看看 求助讨论区。注意！视频教程或者其他网络上的博客和文章可能和本文档有所出入，请以最新版本的本文档所述为准！

安装依赖 #

必须安装的依赖有：Node、JDK 和 Android Studio。

虽然你可以使用 任何编辑器 来开发应用（编写 js 代码），但你仍然必须安装 Android Studio 来获得编译 Android 应用所需的工具和环境。

Node & Watchman #

我们推荐使用 Homebrew 来安装 Node 和 Watchman。在命令行中执行下列命令安装（如安装较慢可以尝试阿里云的 镜像源）：

brew install node@22 brew install watchman

如果你已经安装了 Node，请检查其版本是否在 22.11.0 以上。安装完 Node 后建议设置 npm 镜像（淘宝源）以加速后面的过程（或使用科学上网工具）。

注意：强烈建议始终选择 Node 当前的 LTS（长期维护）版本，一般是偶数版本，不要选择偏实验性质的奇数版本。
注意：不要使用 cnpm！cnpm 安装的模块路径比较奇怪，packager 不能正常识别！
# 使用nrm工具切换淘宝源 npx nrm use taobao # 如果之后需要切换回官方源可使用 npx nrm use npm

Watchman 则是由 Facebook 提供的监视文件系统变更的工具。安装此工具可以提高开发时的性能（packager 可以快速捕捉文件的变化从而实现实时刷新）。

Yarn #

Yarn 是 Facebook 提供的替代 npm 的工具，可以加速 node 模块的下载。

npm install -g yarn

安装完 yarn 之后就可以用 yarn 代替 npm 了，例如用 yarn 代替 npm install 命令，用 yarn add 某第三方库名 代替 npm install 某第三方库名。

Java Development Kit #

我们推荐使用 Homebrew 来安装由 Azul 提供的名为 Zulu 的 OpenJDK 发行版。此发行版同时为 Intel 和 M1 芯片提供支持。在 M1 芯片架构的 Mac 上相比其他 JDK 在编译时有明显的性能优势。

brew install --cask zulu@17 # 获得 JDK 安装程序的路径 brew info --cask zulu@17 # ==> zulu@17: <版本号> # https://www.azul.com/downloads/ # Installed # /opt/homebrew/Caskroom/zulu@17/<版本号> (185.8MB) # 导航到上面打印出来的路径 open /opt/homebrew/Caskroom/zulu@17/<版本号>

安装 JDK 后，请更新 JAVA_HOME 环境变量。React Native 当前需要 Java Development Kit [JDK] 17，不建议使用更高版本或更低版本。

低于 0.73 版本的 React Native 需要 JDK 11 版本，而低于 0.67 的需要 JDK 8 版本。

Android 开发环境 #

如果你之前没有接触过 Android 的开发环境，那么请做好心理准备，这一过程相当繁琐。请 万分仔细 地阅读下面的说明，严格对照文档进行配置操作。

译注：请注意！！！国内用户 必须必须必须 有稳定的代理软件，否则在下载、安装、配置过程中会不断遭遇链接超时或断开，无法进行开发工作。某些代理软件可能只提供浏览器的代理功能，或只针对特定网站代理等等，请自行研究配置或更换其他软件。总之如果报错中出现有网址，那就是因为链接源仓库的网络链接被阻断了，这一阻断现象可能因时间、地区、运营商而不同。
也可以尝试参考这里的做法 设置阿里云的 maven 镜像源，但这个做法可能随 gradle 或者 rn 版本的不同而失效。

1. 安装 Android Studio

首先下载和安装 Android Studio，国内用户可能无法打开官方链接，请自行使用搜索引擎搜索可用的下载链接。安装界面中选择 "Custom" 选项，确保选中了以下几项：

然后点击 "Next" 来安装选中的组件。

如果选择框是灰的，你也可以先跳过，稍后再来安装这些组件。

2. 安装 Android SDK

Android Studio 默认会安装最新版本的 Android SDK。目前编译 React Native 应用需要的是 Android 15 (VanillaIceCream) 版本的 SDK（注意 SDK 版本不等于对用户系统版本的要求）。你可以在 Android Studio 的 SDK Manager 中选择同时安装各种不同版本的 SDK。

在 SDK Manager 中选择 "SDK Platforms" 选项卡，然后在右下角勾选 "Show Package Details"。展开 Android 15 (VanillaIceCream) 选项，确保勾选了下面这些组件：

然后点击 "SDK Tools" 选项卡，同样勾中右下角的 "Show Package Details"。展开 "Android SDK Build-Tools" 选项，确保选中了 React Native 所必须的 36.0.0 版本。你可以同时安装多个其他版本。点击 "Apply" 来下载和安装选中的这些组件。

3. 配置 ANDROID_HOME 环境变量

React Native 需要通过环境变量来了解你的 Android SDK 装在什么路径，从而正常进行编译。具体的做法是把下面的命令加入到 shell 的配置文件中。如果你的 shell 是 zsh，则配置文件为 ~/.zshrc，如果是 bash 则为 ~/.bash_profile（可以使用 echo $0 命令查看你所使用的 shell。）

# 如果你不是通过Android Studio安装的sdk，则其路径可能不同，请自行确定清楚 export ANDROID_HOME=$HOME/Library/Android/sdk export PATH=$PATH:$ANDROID_HOME/emulator export PATH=$PATH:$ANDROID_HOME/platform-tools

使用 source $HOME/.zshrc 命令来使环境变量设置立即生效（否则重启后才生效）。可以使用 echo $ANDROID_HOME 检查此变量是否已正确设置。

请确保你正确指定了 Android SDK 路径。你可以在 Android Studio 的 "Preferences" 菜单中查看 SDK 的真实路径，具体是 Appearance & Behavior → System Settings → Android SDK。

创建新项目 #

使用 React Native 内建的命令行工具来创建一个名为 "AwesomeProject" 的新项目。这个命令行工具不需要安装，可以直接用 node 自带的 npx 命令来使用：

必须要看的注意事项：请 不要 单独使用常见的关键字作为项目名（如 class, native, new, package 等等）。请 不要 使用与核心模块同名的项目名（如 react, react-native 等）。请 不要 在目录、文件名中使用中文、空格等特殊符号。
npx @react-native-community/cli init AwesomeProject

如果你是想把 React Native 集成到现有的原生项目中，则步骤完全不同，请参考 集成到现有原生应用。

[可选参数] 指定版本或项目模板 #

你可以使用 --version 参数（注意是 两 个杠）创建指定版本的项目。例如：

npx @react-native-community/cli init AwesomeProject --version X.XX.X

还可以使用 --template 参数来使用一些社区提供的模板。

准备 Android 设备 #

你需要准备一台 Android 设备来运行 React Native Android 应用。这里所指的设备既可以是真机，也可以是模拟器。后面我们所有的文档除非特别说明，并不区分真机或者模拟器。Android 官方提供了名为 Android Virtual Device（简称 AVD）的模拟器。此外还有很多第三方提供的模拟器如 Genymotion、BlueStack 等。一般来说官方模拟器免费、功能完整，但性能较差。第三方模拟器性能较好，但可能需要付费，或带有广告。

使用 Android 真机 #

你也可以使用 Android 真机来代替模拟器进行开发，只需用 usb 数据线连接到电脑，然后遵照 在设备上运行 这篇文档的说明操作即可。

使用 Android 模拟器 #

你可以使用 Android Studio 打开项目下的 "android" 目录，然后可以使用 "AVD Manager" 来查看可用的虚拟设备。如果你刚刚才安装 Android Studio，那么可能需要先 创建一个虚拟设备。点击 "Create Virtual Device..."，然后选择所需的设备类型并点击 "Next"。

译注：请不要轻易点击 Android Studio 中可能弹出的建议更新项目中某依赖项的建议，否则可能导致无法运行。

编译并运行 React Native 应用 #

确保你先运行了模拟器或者连接了真机，然后在你的项目目录中运行 yarn android 或者 yarn react-native run-android：

cd AwesomeProject yarn android # 或者 yarn react-native run-android

此命令会对项目的原生部分进行编译，同时在另外一个命令行中启动 Metro 服务对 js 代码进行实时打包处理（类似 webpack）。Metro 服务也可以使用 yarn start 命令单独启动。

如果配置没有问题，你应该可以看到应用自动安装到设备上并开始运行。注意第一次运行时需要下载大量编译依赖，耗时可能数十分钟。此过程 严重依赖稳定的代理软件，否则将频繁遭遇链接超时和断开，导致无法运行。

译注：建议在 run-android 成功后再尝试使用 Android Studio 启动。请不要轻易点击 Android Studio 中可能弹出的建议更新项目中某依赖项的建议，否则可能导致无法运行。
如果你无法正常运行，遇到奇奇怪怪的红屏错误，先回头 仔细对照文档检查，然后可以看看 问题讨论区。不同时期不同版本可能会碰到不同的问题，我们会在论坛中及时解答更新。但请注意 千万不要 执行 bundle 命令，那样会导致代码完全无法刷新。

修改项目 #

现在你已经成功运行了项目，我们可以开始尝试动手改一改了：

完成了！ #

恭喜！你已经成功运行并修改了你的第一个 React Native 应用 🎉

接下来？ #

如果你想把 React Native 集成到现有的原生项目中，则请参考 集成到现有原生应用。

如果你想从头开始学习 React Native 开发，可以从 简介 文档开始。

暂不支持 #

注意：苹果公司目前只允许在 Mac 电脑上开发 iOS 应用。如果你没有 Mac 电脑，那么只能考虑使用沙盒环境，或者先开发 Android 应用了。