React Native 开发入门：环境搭建全攻略

引言 / 什么是 React Native

React Native 是 Facebook 推出的开源跨平台移动应用开发框架，允许开发者使用 JavaScript 和 React 语法同时构建 iOS 和 Android 应用。相比原生开发，React Native 通过「一次编写，多端运行」的特性显著提升开发效率，同时保持接近原生的性能表现。无论是初创公司快速验证产品，还是传统企业数字化转型，React Native 都是移动应用开发的热门选择。

本文将系统讲解 React Native 开发环境的搭建流程，涵盖 Windows 和 macOS 两大主流操作系统，并针对 Android 和 iOS 平台分别说明配置要点。通过分步骤的详细指导，即使零基础读者也能顺利完成环境配置，开启移动应用开发之旅。

准备工作

在开始搭建环境前，请确认以下硬件和软件要求：

提示：若需同时开发 iOS 应用，必须使用 macOS 系统，因为 Xcode 仅支持 macOS。

基础操作 / 核心环境搭建

步骤一：安装 Node.js 和 npm/yarn

React Native 基于 Node.js 环境运行，首先需要安装 Node.js（包含 npm 包管理器）：

1. 下载安装包
   访问 Node.js 官网，下载 LTS 版本（推荐 18.x 或更高版本）。

2. 运行安装程序
   Windows 用户双击 .msi 文件，macOS 用户双击 .pkg 文件，按向导完成安装。

3. 验证安装
   打开终端（Windows：cmd 或 PowerShell；macOS：Terminal），执行以下命令：

   node -v
   npm -v
   

   若显示版本号（如 v18.16.0），则安装成功。

提示：推荐使用 yarn 替代 npm 以获得更快的依赖安装速度。安装命令：

npm install -g yarn
yarn -v

步骤二：配置 React Native 命令行工具

React Native 提供官方命令行工具（CLI）用于创建和管理项目：

1. 全局安装 CLI
   在终端执行以下命令：

   npm install -g react-native-cli
   

   或使用 yarn：

   yarn global add react-native-cli
   

2. 验证安装
   执行以下命令查看帮助信息：

   react-native --help
   

步骤三：安装 Android 开发环境（Windows/macOS）

若需开发 Android 应用，需安装 Android Studio 并配置 SDK：

1. 下载 Android Studio
   访问 Android Studio 官网，下载对应操作系统的安装包。

2. 运行安装程序
   按向导完成安装，勾选以下组件：

   • Android SDK
   • Android SDK Platform
   • Android Virtual Device（虚拟设备）

3. 配置环境变量

   • Windows：

     1. 打开「系统属性」→「高级」→「环境变量」。
     2. 在「系统变量」中新建变量 ANDROID_HOME，值为 SDK 安装路径（如 C:\Users\YourName\AppData\Local\Android\Sdk）。
     3. 编辑 Path 变量，添加以下路径：

        %ANDROID_HOME%\platform-tools
        %ANDROID_HOME%\tools
        

   • macOS：

     1. 打开终端，编辑 ~/.zshrc（或 ~/.bash_profile）文件：

        nano ~/.zshrc
        

     2. 添加以下内容（路径根据实际安装位置调整）：

        export ANDROID_HOME=$HOME/Library/Android/sdk
        export PATH=$PATH:$ANDROID_HOME/platform-tools:$ANDROID_HOME/tools
        

     3. 保存文件并执行 source ~/.zshrc 使配置生效。

4. 验证配置
   执行以下命令检查 Android 工具是否可用：

   adb version
   

   若显示版本号（如 Android Debug Bridge version 1.0.41），则配置成功。

步骤四：安装 Xcode（仅 macOS）

若需开发 iOS 应用，必须安装 Xcode（App Store 搜索并安装）：

1. 安装 Xcode
   打开 App Store，搜索「Xcode」，点击「获取」安装（约 12GB）。

2. 安装命令行工具
   打开 Xcode，进入 【Preferences】→【Components】，安装最新版本的 Command Line Tools。

3. 验证安装
   执行以下命令检查 Xcode 工具链：

   xcode-select --install
   xcodebuild -version
   

进阶技巧

技巧一：使用真机调试

相比模拟器，真机调试能更真实地反映应用性能：

1. Android 设备

   • 启用开发者模式：进入 【设置】→【关于手机】，连续点击「版本号」7 次。
   • 启用 USB 调试：进入 【开发者选项】，勾选「USB 调试」。
   • 连接设备到电脑，执行 adb devices 确认设备已识别。

2. iOS 设备

   • 使用数据线连接设备到 Mac。
   • 在 Xcode 中，选择 【Window】→【Devices and Simulators】，确认设备已列出。

技巧二：加速依赖安装

国内开发者可通过配置镜像源加速 npm/yarn 依赖安装：

1. npm 配置淘宝镜像

   npm config set registry https://registry.npmmirror.com
   

2. yarn 配置淘宝镜像

   yarn config set registry https://registry.npmmirror.com
   

技巧三：常用环境变量配置

以下环境变量可优化 React Native 开发体验：

常见问题

Q：执行 react-native run-android 时报错「Could not install the app on the device」？
A：可能是设备未授权或端口冲突。尝试以下步骤：

1. 确保设备已启用 USB 调试并授权电脑。
2. 终止所有正在运行的 adb 进程：

   adb kill-server
   adb start-server
   

3. 检查 Metro 端口是否被占用：

   lsof -i :8081  # macOS/Linux
   netstat -ano | findstr 8081  # Windows
   

Q：iOS 模拟器启动后显示白屏？
A：可能是 Xcode 项目配置问题。尝试以下操作：

1. 删除 ios 目录下的 build 文件夹。
2. 执行 cd ios && pod install 重新安装 CocoaPods 依赖。
3. 在 Xcode 中清理项目： 【Product】→【Clean Build Folder】。

Q：如何解决「Unable to load script from assets index.android.bundle」错误？
A：此错误通常因 Metro 打包失败导致。尝试：

1. 删除 android/app/build 文件夹。
2. 重新运行项目时添加 --reset-cache 参数：

   react-native run-android --reset-cache
   

小结

本文系统讲解了 React Native 开发环境的搭建流程，涵盖 Node.js、React Native CLI、Android Studio/Xcode 等核心工具的安装与配置。通过分步骤的指导，读者已能独立完成环境搭建并验证基础项目运行。建议新手从官方示例项目 AwesomeProject 开始实践，逐步掌握组件开发、状态管理和跨平台适配等高级技能。

环境配置是 React Native 开发的第一步，后续还需深入学习 React 语法、导航组件、状态管理（如 Redux 或 Context API）等知识。保持耐心，多查阅 官方文档和社区资源，你将成为高效的跨平台开发者！