0.44

帮助改进此文档

搭建开发环境

欢迎使用 React Native！这篇文档会帮助你搭建基本的 React Native 开发环境。如果你已经搭好了环境，那么可以尝试一下编写 Hello World。

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

如果阅读完本文档后还碰到很多环境搭建的问题，我们建议你还可以再看看由本站提供的环境搭建视频教程(macOS iOS、macOS Android、windows Android)、windows 环境搭建文字教程、以及常见问题。

目标平台： iOS Android 开发平台： macOS Linux Windows

暂不支持

苹果公司目前只允许在 Mac 电脑上开发 iOS 应用。如果你没有 Mac 电脑，那么只能考虑先开发 Android 应用了。

安装

必需的软件

Homebrew

Homebrew, Mac 系统的包管理器，用于安装 NodeJS 和一些其他必需的工具软件。

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

译注：在 Max OS X 10.11（El Capitan)版本中，homebrew 在安装软件时可能会碰到/usr/local目录不可写的权限问题。可以使用下面的命令修复：

sudo chown -R `whoami` /usr/local

Node

使用 Homebrew 来安装Node.js.

React Native 目前需要 NodeJS 5.0 或更高版本。本文发布时 Homebrew 默认安装的是最新版本，一般都满足要求。

brew install node

安装完 node 后建议设置 npm 镜像以加速后面的过程（或使用科学上网工具）。注意：不要使用 cnpm！cnpm 安装的模块路径比较奇怪，packager 不能正常识别！

npm config set registry https://registry.npm.taobao.org --global
npm config set disturl https://npm.taobao.org/dist --global

Yarn、React Native 的命令行工具（react-native-cli）

Yarn是 Facebook 提供的替代 npm 的工具，可以加速 node 模块的下载。React Native 的命令行工具用于执行创建、初始化、更新项目、运行打包服务（packager）等任务。

npm install -g yarn react-native-cli

安装完 yarn 后同理也要设置镜像源：

yarn config set registry https://registry.npm.taobao.org --global
yarn config set disturl https://npm.taobao.org/dist --global

如果你看到EACCES: permission denied这样的权限报错，那么请参照上文的 homebrew 译注，修复/usr/local目录的所有权：

sudo chown -R `whoami` /usr/local

Xcode

React Native 目前需要Xcode 8.0 或更高版本。你可以通过 App Store 或是到Apple 开发者官网上下载。这一步骤会同时安装 Xcode IDE 和 Xcode 的命令行工具。

虽然一般来说命令行工具都是默认安装了，但你最好还是启动 Xcode，并在Xcode | Preferences | Locations菜单中检查一下是否装有某个版本的Command Line Tools。Xcode 的命令行工具中也包含一些必须的工具，比如git等。

Android Studio

React Native 目前需要Android Studio2.0 或更高版本。

Android Studio 需要 Java Development Kit [JDK] 1.8 或更高版本。你可以在命令行中输入 javac -version来查看你当前安装的 JDK 版本。如果版本不合要求，则可以到 官网上下载。

Android Studio 包含了运行和测试 React Native 应用所需的 Android SDK 和模拟器。

除非特别注明，请不要改动安装过程中的选项。比如 Android Studio 默认安装了 Android Support Repository，而这也是 React Native 必须的（否则在 react-native run-android 时会报 appcompat-v7 包找不到的错误）。

安装过程中有一些需要改动的选项：

  • 选择Custom选项：

custom installation

  • 勾选Performance和Android Virtual Device

additional installs

  • 安装完成后，在 Android Studio 的启动欢迎界面中选择Configure | SDK Manager。

configure sdk

  • 在SDK Platforms窗口中，选择Show Package Details，然后在Android 6.0 (Marshmallow)中勾选Google APIs、Android SDK Platform 23、Intel x86 Atom System Image、Intel x86 Atom_64 System Image以及Google APIs Intel x86 Atom_64 System Image。

platforms

  • 在SDK Tools窗口中，选择Show Package Details，然后在Android SDK Build Tools中勾选Android SDK Build-Tools 23.0.1（必须是这个版本）。然后还要勾选最底部的Android Support Repository.

build tools

ANDROID_HOME 环境变量

确保ANDROID_HOME环境变量正确地指向了你安装的 Android SDK 的路径。具体的做法是把下面的命令加入到~/.bash_profile文件中：(译注：~表示用户目录，即/Users/你的用户名/，而小数点开头的文件在 Finder 中是隐藏的，并且这个文件有可能并不存在。请在终端下使用vi ~/.bash_profile命令创建或编辑。如不熟悉 vi 操作，请点击这里学习）

# 如果你不是通过Android Studio安装的sdk，则其路径可能不同，请自行确定清楚。
export ANDROID_HOME=~/Library/Android/sdk

然后使用下列命令使其立即生效（否则重启后才生效）：

source ~/.bash_profile

可以使用echo $ANDROID_HOME检查此变量是否已正确设置。

推荐安装的工具

Watchman

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

brew install watchman

Flow

Flow是一个静态的 JS 类型检查工具。译注：你在很多示例中看到的奇奇怪怪的冒号问号，以及方法参数中像类型一样的写法，都是属于这个 flow 工具的语法。这一语法并不属于 ES 标准，只是 Facebook 自家的代码规范。所以新手可以直接跳过（即不需要安装这一工具，也不建议去费力学习 flow 相关语法）。

brew install flow

将 Android SDK 的 Tools 目录添加到PATH变量中

你可以把 Android SDK 的 tools 和 platform-tools 目录添加到PATH变量中，以便在终端中运行一些 Android 工具，例如android avd或是adb logcat等。具体做法仍然是在~/.bash_profile中添加：

export PATH=$PATH:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools

其他可选的安装项

Git

Git 版本控制。如果你已经安装过Xcode，则 Git 也已经一并安装了。如若没有，则使用下列命令安装：

brew install git

Nuclide

Nuclide（此链接需要科学上网）是由 Facebook 提供的基于 atom 的集成开发环境，可用于编写、运行和 调试React Native 应用。

点击这里阅读Nuclide 的入门文档。

译注：我们更推荐使用WebStorm或Sublime Text来编写 React Native 应用。

Genymotion

比起 Android Studio 自带的原装模拟器，Genymotion 是一个性能更好的选择，但它只对个人用户免费。

  1. 下载和安装Genymotion（genymotion 需要依赖 VirtualBox 虚拟机，下载选项中提供了包含 VirtualBox 和不包含的选项，请按需选择）。
  2. 打开 Genymotion。如果你还没有安装 VirtualBox，则此时会提示你安装。
  3. 创建一个新模拟器并启动。
  4. 启动 React Native 应用后，可以按下 ⌘+M 来打开开发者菜单。

安装

必需的软件

Chocolatey

Chocolatey是一个 Windows 上的包管理器，类似于 linux 上的yum和 apt-get。 你可以在其官方网站上查看具体的使用说明。一般的安装步骤应该是下面这样：

@powershell -NoProfile -ExecutionPolicy Bypass -Command "iex ((new-object net.webclient).DownloadString('https://chocolatey.org/install.ps1'))" && SET PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin

一般来说，使用 Chocolatey 来安装软件的时候，需要以管理员的身份来运行命令提示符窗口。译注：chocolatey 的网站可能在国内访问困难，导致上述安装命令无法正常完成。请使用稳定的翻墙工具。 如果你实在装不上这个工具，也不要紧。下面所需的 python2 和 nodejs 你可以分别单独去对应的官方网站下载安装即可。

Python 2

打开命令提示符窗口，使用 Chocolatey 来安装 Python 2.

注意目前不支持 Python 3 版本。

choco install python2

Node

打开终端窗口，输入下面的命令来安装 NodeJS:

sudo apt-get install -y build-essential
curl -sL https://deb.nodesource.com/setup_5.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo ln -s /usr/bin/nodejs /usr/bin/node

打开命令提示符窗口，使用 Chocolatey 来安装 NodeJS。注意，目前已知 Node 7.1 版本在 windows 上无法正常工作，请避开这个版本！

choco install nodejs.install

安装完 node 后建议设置 npm 镜像以加速后面的过程（或使用科学上网工具）。注意：不要使用 cnpm！cnpm 安装的模块路径比较奇怪，packager 不能正常识别！

npm config set registry https://registry.npm.taobao.org --global
npm config set disturl https://npm.taobao.org/dist --global

Yarn、React Native 的命令行工具（react-native-cli）

Yarn是 Facebook 提供的替代 npm 的工具，可以加速 node 模块的下载。React Native 的命令行工具用于执行创建、初始化、更新项目、运行打包服务（packager）等任务。

npm install -g yarn react-native-cli

安装完 yarn 后同理也要设置镜像源：

yarn config set registry https://registry.npm.taobao.org --global
yarn config set disturl https://npm.taobao.org/dist --global

如果你遇到EACCES: permission denied权限错误，可以尝试运行下面的命令（限 linux 系统）： sudo npm install -g yarn react-native-cli.

Android Studio

Android Studio 2.0 or higher.

React Native 目前需要Android Studio2.0 或更高版本。

Android Studio 需要 Java Development Kit [JDK] 1.8 或更高版本。你可以在命令行中输入 javac -version来查看你当前安装的 JDK 版本。如果版本不合要求，则可以到 官网上下载。 或是使用包管理器来安装（比如choco install jdk8或是 apt-get install default-jdk）

Android Studio 包含了运行和测试 React Native 应用所需的 Android SDK 和模拟器。

除非特别注明，请不要改动安装过程中的选项。比如 Android Studio 默认安装了 Android Support Repository，而这也是 React Native 必须的（否则在 react-native run-android 时会报 appcompat-v7 包找不到的错误）。

安装过程中有一些需要改动的选项：

  • 选择Custom选项：

custom installation

  • 选择Android Virtual Device

additional installs

  • 确定所有安装都勾选了，尤其是Android SDK和Android Device Emulator。

  • 在初步安装完成后，选择Custom安装项：

custom installation

  • 检查已安装的组件，尤其是模拟器和 HAXM 加速驱动。

verify installs

  • 安装完成后，在 Android Studio 的欢迎界面中选择Configure | SDK Manager。

configure sdk

configure sdk

  • 在SDK Platforms窗口中，选择Show Package Details，然后在Android 6.0 (Marshmallow)中勾选Google APIs、Android SDK Platform 23、Intel x86 Atom System Image、Intel x86 Atom_64 System Image以及Google APIs Intel x86 Atom_64 System Image。

platforms

platforms

  • 在SDK Tools窗口中，选择Show Package Details，然后在Android SDK Build Tools中勾选Android SDK Build-Tools 23.0.1（必须是这个版本）。然后还要勾选最底部的Android Support Repository.

build tools

build tools

ANDROID_HOME 环境变量

确保ANDROID_HOME环境变量正确地指向了你安装的 Android SDK 的路径。

具体的做法是把下面的命令加入到~/.bashrc、~/.bash_profile文件中。如果你使用的是其他的 shell，则选择对应的配置文件:

# 如果你不是通过Android Studio安装的sdk，则其路径可能不同，请自行确定清楚。
export ANDROID_HOME=~/Library/Android/sdk

然后使用下列命令使其立即生效（否则重启后才生效）：

source ~/.bash_profile

可以使用echo $ANDROID_HOME检查此变量是否已正确设置。

打开控制面板 -> 系统和安全 -> 系统 -> 高级系统设置 -> 高级 -> 环境变量 -> 新建

具体的路径可能和下图不一致，请自行确认。

env variable

你需要关闭现有的命令符提示窗口然后重新打开，这样新的环境变量才能生效。

推荐安装的工具

Watchman

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

安装 watchman 还可以避免 node 的一个与文件监视有关的 bug。

在终端中输入以下命令来编译并安装 watchman:

git clone https://github.com/facebook/watchman.git
cd watchman
git checkout v4.5.0  # 这是本文发布时的最新版本
./autogen.sh
./configure
make
sudo make install

Flow

Flow是一个静态的 JS 类型检查工具。译注：你在很多示例中看到的奇奇怪怪的冒号问号，以及方法参数中像类型一样的写法，都是属于这个 flow 工具的语法。这一语法并不属于 ES 标准，只是 Facebook 自家的代码规范。所以新手可以直接跳过（即不需要安装这一工具，也不建议去费力学习 flow 相关语法）。

在终端中输入以下命令来安装 flow:

npm install -g flow-bin

Gradle Daemon

开启Gradle Daemon可以极大地提升 java 代码的增量编译速度。

touch ~/.gradle/gradle.properties && echo "org.gradle.daemon=true" >> ~/.gradle/gradle.properties

(if not exist "%USERPROFILE%/.gradle" mkdir "%USERPROFILE%/.gradle") && (echo org.gradle.daemon=true >> "%USERPROFILE%/.gradle/gradle.properties")

Android 模拟器加速器

在安装 Android Studio 时你可能会看到下面这样的提示：

accelerator

如果你的系统支持 KVM，那就应该安装Intel 的 Android 模拟器加速器。

将 Android SDK 的 Tools 目录添加到PATH变量中

你可以把 Android SDK 的 tools 和 platform-tools 目录添加到PATH变量中，以便在终端中运行一些 Android 工具，例如android avd或是adb logcat等。

在~/.bashrc或是~/.bash_profile文件中添加：

# 你的具体路径可能有所不同，请自行确认。
PATH="~/Android/Sdk/tools:~/Android/Sdk/platform-tools:${PATH}"
export PATH

打开控制面板 -> 系统和安全 -> 系统 -> 高级系统设置 -> 高级 -> 环境变量 -> 选中PATH -> 双击进行编辑

注意你的具体路径可能和下图不同

env variable

可选的安装项

Git

使用包管理器来安装 Git (例如sudo apt-get install git-all).

你可以使用 Chocolatey 来安装git:

choco install git

另外你也可以直接去下载Git for Windows。 在安装过程中注意勾选"Run Git from Windows Command Prompt"，这样才会把git命令添加到PATH环境变量中。

Nuclide

Nuclide（此链接需要科学上网）是由 Facebook 提供的基于 atom 的集成开发环境，可用于编写、运行和 调试React Native 应用。

点击这里阅读Nuclide 的入门文档。

译注：我们更推荐使用WebStorm或Sublime Text来编写 React Native 应用。

Genymotion

比起 Android Studio 自带的原装模拟器，Genymotion 是一个性能更好的选择，但它只对个人用户免费。

  1. 下载和安装Genymotion（genymotion 需要依赖 VirtualBox 虚拟机，下载选项中提供了包含 VirtualBox 和不包含的选项，请按需选择）。
  2. 打开 Genymotion。如果你还没有安装 VirtualBox，则此时会提示你安装。
  3. 创建一个新模拟器并启动。
  4. 启动 React Native 应用后，可以按下 F1 来打开开发者菜单。

Visual Studio Emulator for Android

Visual Studio Emulator for Android是利用了 Hyper-V 技术进行硬件加速的免费 android 模拟器。也是 Android Studio 自带的原装模拟器之外的一个很好的选择。而且你并不需要安装 Visual Studio。 在用于 React Native 开发前，需要先在注册表中进行一些修改：

  1. 打开运行命令（按下 Windows+R 键）
  2. 输入regedit.exe然后回车
  3. 在注册表编辑器中找到HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Android SDK Tools条目
  4. 右键点击Android SDK Tools，选择新建 > 字符串值
  5. 名称设为Path
  6. 双击Path，将其值设为你的 Android SDK 的路径。（例如C:\Program Files\Android\sdk）

测试安装

react-native init AwesomeProject
cd AwesomeProject
react-native run-ios

提示：你可以使用--version参数创建指定版本的项目。例如react-native init MyApp --version 0.39.2。注意版本号必须精确到两个小数点。

你也可以在Nuclide中打开AwesomeProject文件夹 然后运行，或是双击ios/AwesomeProject.xcodeproj文件然后在 Xcode 中点击Run按钮。

react-native init AwesomeProject
cd AwesomeProject
react-native run-android

提示：你可以使用--version参数创建指定版本的项目。例如react-native init MyApp --version 0.39.2。注意版本号必须精确到两个小数点。

你也可以在Nuclide中打开AwesomeProject文件夹然后运行。

修改项目

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

  • 使用你喜欢的编辑器打开index.ios.js并随便改上几行。
  • 在 iOS Emulator 中按下⌘-R就可以刷新 APP 并看到你的最新修改！
  • 使用你喜欢的文本编辑器打开index.android.js并随便改上几行
  • 按两下 R 键，或是用 Menu 键（通常是 F2，在 Genymotion 模拟器中是⌘+M）打开开发者菜单，然后选择 Reload JS 就可以看到你的最新修改。
  • 在终端下运行adb logcat *:S ReactNative:V ReactNativeJS:V可以看到你的应用的日志。

完成了！

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

测试安装

react-native init AwesomeProject
cd AwesomeProject
react-native run-android

提示：你可以使用--version参数创建指定版本的项目。例如react-native init MyApp --version 0.39.2。注意版本号必须精确到两个小数点。

Windows 用户请注意，请不要在命令行默认的 System32 目录中 init 项目！会有各种权限限制导致不能运行！

修改项目

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

  • 使用你喜欢的文本编辑器打开index.android.js并随便改上几行
  • 按两下 R 键，或是用 Menu 键（通常是 F2，在 Genymotion 模拟器中是⌘+M）打开开发者菜单，然后选择 Reload JS 就可以看到你的最新修改。
  • 在终端下运行adb logcat *:S ReactNative:V ReactNativeJS:V可以看到你的应用的日志。

完成了！

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

接下来

接下来

示例教程：Hello World →