Skip to main content

故障排除

这些是你在设置 React Native 时可能遇到的一些常见问题。如果你遇到此处未列出的内容，请尝试 在 GitHub 中搜索问题。

¥These are some common issues you may run into while setting up React Native. If you encounter something that is not listed here, try searching for the issue in GitHub.

端口已在使用中​

¥Port already in use

Metro 打包器 在端口 8081 上运行。如果另一个进程已在使用该端口，你可以终止该进程，或更改打包程序使用的端口。

¥The Metro bundler runs on port 8081. If another process is already using that port, you can either terminate that process, or change the port that the bundler uses.

终止端口 8081 上的进程​

¥Terminating a process on port 8081

运行以下命令查找正在监听端口 8081 的进程的 ID：

¥Run the following command to find the id for the process that is listening on port 8081:

sudo lsof -i :8081

然后运行以下命令来终止该进程：

¥Then run the following to terminate the process:

kill -9 <PID>

在 Windows 上，你可以使用 资源监控器 找到使用端口 8081 的进程，并使用任务管理器停止它。

¥On Windows you can find the process using port 8081 using Resource Monitor and stop it using Task Manager.

使用 8081 以外的端口​

¥Using a port other than 8081

你可以使用 port 参数将打包程序配置为使用 8081 以外的端口，从项目的根目录运行：

¥You can configure the bundler to use a port other than 8081 by using the port parameter, from the root of your project run:

npm start -- --port=8088

你还需要更新应用以从新端口加载 JavaScript 包。如果从 Xcode 在设备上运行，你可以通过将 8081 的出现更新到 ios/__App_Name__.xcodeproj/project.pbxproj 文件中你选择的端口来完成此操作。

¥You will also need to update your applications to load the JavaScript bundle from the new port. If running on device from Xcode, you can do this by updating occurrences of 8081 to your chosen port in the ios/__App_Name__.xcodeproj/project.pbxproj file.

NPM 锁定错误​

¥NPM locking error

如果你在使用 React Native CLI 时遇到诸如 npm WARN locking Error: EACCES 之类的错误，请尝试运行以下命令：

¥If you encounter an error such as npm WARN locking Error: EACCES while using the React Native CLI, try running the following:

sudo chown -R $USER ~/.npm
sudo chown -R $USER /usr/local/lib/node_modules

缺少 React 库​

¥Missing libraries for React

如果你手动将 React Native 添加到项目中，请确保已包含你正在使用的所有相关依赖，例如 RCTText.xcodeproj、RCTImage.xcodeproj。接下来，由这些依赖构建的二进制文件必须链接到你的应用二进制文件。使用 Xcode 项目设置中的 Linked Frameworks and Binaries 部分。更详细的步骤在这里：连接库。

¥If you added React Native manually to your project, make sure you have included all the relevant dependencies that you are using, like RCTText.xcodeproj, RCTImage.xcodeproj. Next, the binaries built by these dependencies have to be linked to your app binary. Use the Linked Frameworks and Binaries section in the Xcode project settings. More detailed steps are here: Linking Libraries.

如果你使用的是 CocoaPods，请验证你是否已将 React 以及子规范添加到 Podfile。例如，如果你使用 <Text />、<Image /> 和 fetch() API，则需要将这些添加到 Podfile 中：

¥If you are using CocoaPods, verify that you have added React along with the subspecs to the Podfile. For example, if you were using the <Text />, <Image /> and fetch() APIs, you would need to add these in your Podfile:

pod 'React', :path => '../node_modules/react-native', :subspecs => [
  'RCTText',
  'RCTImage',
  'RCTNetwork',
  'RCTWebSocket',
]

接下来，确保你已运行 pod install 并且已在安装了 React 的项目中创建了 Pods/ 目录。CocoaPods 将指示你使用生成的 .xcworkspace 文件，以便能够使用这些已安装的依赖。

¥Next, make sure you have run pod install and that a Pods/ directory has been created in your project with React installed. CocoaPods will instruct you to use the generated .xcworkspace file henceforth to be able to use these installed dependencies.

React Native 用作 CocoaPod 时无法编译​

¥React Native does not compile when being used as a CocoaPod

有一个名为 cocoapods-fix-react-native 的 CocoaPods 插件，它可以处理由于使用依赖管理器时的差异而导致的任何潜在的源代码后修复。

¥There is a CocoaPods plugin called cocoapods-fix-react-native which handles any potential post-fixing of the source code due to differences when using a dependency manager.

参数列表太长：递归标头扩展失败​

¥Argument list too long: recursive header expansion failed

在项目的构建设置中，User Search Header Paths 和 Header Search Paths 是两个配置，它们指定 Xcode 应在何处查找代码中指定的 #import 头文件。对于 Pods，CocoaPods 使用特定文件夹的默认数组进行查找。验证此特定配置没有被覆盖，并且配置的文件夹都没有太大。如果其中一个文件夹是一个大文件夹，Xcode 将尝试递归搜索整个目录并在某个时刻抛出上述错误。

¥In the project's build settings, User Search Header Paths and Header Search Paths are two configs that specify where Xcode should look for #import header files specified in the code. For Pods, CocoaPods uses a default array of specific folders to look in. Verify that this particular config is not overwritten, and that none of the folders configured are too large. If one of the folders is a large folder, Xcode will attempt to recursively search the entire directory and throw above error at some point.

将 User Search Header Paths 和 Header Search Paths 构建设置恢复为 CocoaPods 设置的默认值 - 选择“构建设置”面板中的条目，然后单击“删除”。它将删除自定义覆盖并返回到 CocoaPod 默认值。

¥To revert the User Search Header Paths and Header Search Paths build settings to their defaults set by CocoaPods - select the entry in the Build Settings panel, and hit delete. It will remove the custom override and return to the CocoaPod defaults.

没有可用的传输工具​

¥No transports available

React Native 为 WebSocket 实现了一个 polyfill。这些 polyfills 作为你通过 import React from 'react' 包含在应用中的 React-Native 模块的一部分进行初始化。如果你加载另一个需要 WebSocket 的模块，例如 Firebase，请务必在 react-native 之后加载/需要它：

¥React Native implements a polyfill for WebSockets. These polyfills are initialized as part of the react-native module that you include in your application through import React from 'react'. If you load another module that requires WebSockets, such as Firebase, be sure to load/require it after react-native:

import React from 'react';
import Firebase from 'firebase';

Shell 命令无响应异常​

¥Shell Command Unresponsive Exception

如果遇到 ShellCommandUnresponsiveException 异常，例如：

¥If you encounter a ShellCommandUnresponsiveException exception such as:

Execution failed for task ':app:installDebug'.
  com.android.builder.testing.api.DeviceException: com.android.ddmlib.ShellCommandUnresponsiveException

在 android/build.gradle 中尝试 将 Gradle 版本降级到 1.2.3。

¥Try downgrading your Gradle version to 1.2.3 in android/build.gradle.

React Native 初始化挂起​

¥react-native init hangs

如果你遇到系统中运行 npx react-native init 挂起的问题，请尝试在详细模式下再次运行它，并参考 #2797 了解常见原因：

¥If you run into issues where running npx react-native init hangs in your system, try running it again in verbose mode and referring to #2797 for common causes:

npx react-native init --verbose

当你正在调试进程或需要更多地了解所引发的错误时，你可能需要使用 verbose 选项来输出更多日志和信息来确定你的问题。

¥When you're debugging a process or need to know a little more about the error being thrown, you may want to use the verbose option to output more logs and information to nail down your issue.

在项目的根目录中运行以下命令。

¥Run the following command in your project's root directory.

npm run android -- --verbose

无法启动 react-native 包管理器（在 Linux 上）​

¥Unable to start react-native package manager (on Linux)

情况 1：错误 "code":"ENOSPC","errno":"ENOSPC"​

¥Case 1: Error "code":"ENOSPC","errno":"ENOSPC"

由 inotify（Linux 上的 watchman 使用）可以监控的目录数量引起的问题。要解决此问题，请在终端窗口中运行此命令

¥Issue caused by the number of directories inotify (used by watchman on Linux) can monitor. To solve it, run this command in your terminal window

echo fs.inotify.max_user_watches=582222 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p

错误：spawnSync ./gradlew EACCES​

¥Error: spawnSync ./gradlew EACCES

如果你遇到在 macOS 上执行 npm run android 或 yarn android 引发上述错误的问题，请尝试运行 sudo chmod +x android/gradlew 命令以使 gradlew 文件成为可执行文件。

¥If you run into issue where executing npm run android or yarn android on macOS throws the above error, try to run sudo chmod +x android/gradlew command to make gradlew files into executable.