疑难解答
本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。 发现错误？ 报告问题 →
以下是设置 React Native 时可能遇到的一些常见问题。如果遇到未列出的问题，请尝试在 GitHub 上搜索相关议题。
端口已被占用
Metro 打包器默认运行在 8081 端口。如果其他进程已占用该端口，您可以终止该进程或更改打包器使用的端口。
终止占用 8081 端口的进程
运行以下命令查找监听 8081 端口的进程 ID：
sudo lsof -i :8081
然后运行以下命令终止该进程：
kill -9 <PID>
在 Windows 系统中，您可以使用资源监视器查找占用 8081 端口的进程，并通过任务管理器终止它。
使用 8081 以外的端口
您可以通过 port 参数配置打包器使用其他端口，在项目根目录运行：
- npm
- Yarn
npm start -- --port=8088
yarn start --port 8088
同时需要更新应用程序以从新端口加载 JavaScript 包。如果在 Xcode 中真机运行时，需在 ios/__App_Name__.xcodeproj/project.pbxproj 文件中将所有 8081 替换为您选择的端口号。
NPM 锁定错误
如果在使用 React Native CLI 时遇到类似 npm WARN locking Error: EACCES 的错误，请尝试运行：
sudo chown -R $USER ~/.npm
sudo chown -R $USER /usr/local/lib/node_modules
React 库缺失
如果是手动将 React Native 添加到项目，请确保包含所有正在使用的依赖项，如 RCTText.xcodeproj、RCTImage.xcodeproj。接着需要将这些依赖构建的二进制文件链接到应用二进制文件。在 Xcode 项目设置的 Linked Frameworks and Binaries 部分操作。详细步骤参考：链接库。
如果使用 CocoaPods，请确认已在 Podfile 中添加 React 及对应子模块。例如，若使用 <Text />、<Image /> 和 fetch() API，需在 Podfile 中添加：
pod 'React', :path => '../node_modules/react-native', :subspecs => [
'RCTText',
'RCTImage',
'RCTNetwork',
'RCTWebSocket',
]
确保运行 pod install 后项目中生成包含 React 的 Pods/ 目录。CocoaPods 会提示后续使用生成的 .xcworkspace 文件来调用这些依赖。
作为 CocoaPod 使用时编译失败
可使用 cocoapods-fix-react-native 插件处理依赖管理器导致的源码修复问题。
参数列表过长：递归头文件扩展失败
在项目构建设置中，User Search Header Paths 和 Header Search Paths 指定了 Xcode 查找代码中 #import 头文件的位置。CocoaPods 为 Pods 设置了默认的特定搜索文件夹。请确认该配置未被覆盖，且所有配置文件夹均未过大。若某个文件夹过大，Xcode 尝试递归搜索整个目录时会触发此错误。
要恢复 CocoaPods 设置的 User Search Header Paths 和 Header Search Paths 默认值：在构建设置面板中选择对应条目，按删除键。这将移除自定义覆盖并恢复 CocoaPod 默认设置。
无可用传输方式
React Native 实现了 WebSockets 的 polyfill。这些 polyfill 会随着你在应用中通过 import React from 'react' 引入的 react-native 模块一起初始化。如果你需要加载其他依赖 WebSockets 的模块（例如 Firebase），请确保在 react-native 之后加载/引入：
import React from 'react';
import Firebase from 'firebase';
Shell 命令无响应异常
如果遇到 ShellCommandUnresponsiveException 异常，例如：
Execution failed for task ':app:installDebug'.
com.android.builder.testing.api.DeviceException: com.android.ddmlib.ShellCommandUnresponsiveException
尝试在 android/build.gradle 中将 Gradle 版本降级到 1.2.3。
react-native init 卡住
如果您在运行 npx react-native init 时遇到卡住的问题，请尝试在详细模式下重新运行，并参考 #2797 来了解常见原因：
npx react-native init --verbose
当你在调试一个进程或需要更详细了解所抛出的错误时，你可能想要使用详细模式来输出更多日志和信息，以锁定你的问题。
调试进程或需要获取更多错误信息时，可以使用详细模式输出更多日志信息来定位问题：
- npm
- Yarn
npm run android -- --verbose
yarn android --verbose
在项目根目录下运行以下命令：
无法启动 react-native 包管理器（Linux 系统）
问题是由 inotify（在 Linux 上由 watchman 使用）可以监视的目录数量限制引起的。要解决此问题，请在终端窗口中运行此命令。
echo fs.inotify.max_user_watches=582222 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p
错误：spawnSync ./gradlew EACCES
如果在 macOS 上执行 npm run android 或 yarn android 时遇到问题并抛出上述错误，请尝试运行 sudo chmod +x android/gradlew 命令，使 gradlew 文件成为可执行文件。