前言

最近前同事问我react-native方面的问题，几年前我粗略地学习过react-native的开发，时至今日，差不多又还回去了。于是就搜索react-native方面的文章看。看到这篇文章，对评论区一个掘友的留言很好奇，这款用react-native开发的仿掘金APP的应用，界面到底长什么样子？文中的作者并没有截屏展示。于是打算把文中的项目下载下来，运行一下，看看效果。过程没有我想得那么顺利，一波三折，踩了一些坑，好在最后跑起来了，在Android Studio模拟器中的运行效果如下图所示。现在我们回溯一个过程，把遇到的问题的解决方法给大家分享一下。

创建项目

npx react-native init react-native-junjin

生成的目录结构如下图所示：

react-native-junjin/
├── __tests__/                // 测试目录，包含测试文件
├── android/                  // Android 项目的原生代码
├── ios/                      // iOS 项目的原生代码
├── node_modules/             // Node.js 模块目录，包含所有依赖包
├── .eslintrc.js              // ESLint 配置文件，用于 JavaScript 代码风格检查
├── .gitignore                // Git 忽略文件配置
├── .prettierrc.js            // Prettier 配置文件，用于代码格式化
├── .watchmanconfig           // Watchman 配置文件，用于监视文件变化
├── App.tsx                   // 主要的 React 组件文件，使用 TypeScript 编写
├── app.json                  // 应用的配置文件
├── babel.config.js           // Babel 配置文件，用于 JavaScript 转译
├── index.js                  // JavaScript 入口文件，注册根组件
├── metro.config.js           // Metro bundler 配置文件
├── package.json              // 项目的包管理配置文件，定义项目依赖及脚本
├── README.md                 // 项目说明文件
├── yarn.lock                 // Yarn 锁定文件，确保依赖版本一致
├── .bundle/                  // 这个文件夹通常包含打包配置和缓存，用于优化打包过程
├── Gemfile                   // Ruby 的依赖管理文件，，通常与 CocoaPods 一起使用，以管理 iOS 项目的依赖。
├── jest.config.js            // Jest 配置文件，用于测试设置
├── tsconfig.json             // TypeScript 配置文件
└── .yarnrc.yml               // Yarn 配置文件，定义 Yarn 的行为

别的文件都好理解，对于初学者，可能不知道Metro和Gemfile是干什么的。

Metro 是 React Native 项目中开发工具链的重要组成部分。Metro 是 React Native 的 JavaScript 打包器，将所有的 JavaScript 文件打包成一个或多个文件，以便应用程序可以在设备或模拟器上运行。它会解析项目中的依赖关系树，将所有依赖项捆绑在一起，生成一个高效的包。它具有快速增量构建、热重载和代码拆分等功能使得开发过程更加高效和便捷。项目的根目录下有一个 metro.config.js 文件，用于配置 Metro 的行为。这个文件可以包含如下配置：

• Transformer 配置：指定如何转译文件。
• Resolver 配置：定义如何解析模块路径。
• Cache 配置：配置缓存的行为。
• Server 配置：配置开发服务器的选项。

配置示例：

module.exports = {
  transformer: {
    babelTransformerPath: require.resolve('react-native-typescript-transformer'),
  },
  resolver: {
    sourceExts: ['jsx', 'js', 'ts', 'tsx'], // 支持的文件扩展名
  },
};

Gemfile 在一个 React Native 项目中，Gemfile 通常用于管理 iOS 开发所需的 RubyGems。RubyGems 是 Ruby 的包管理系统，Gemfile 的主要作用是列出项目所依赖的所有 gems（RubyGems所管理的包或者依赖，我们称之为 gem），并确保在不同环境下这些依赖项的一致性，其中一个比较重要的gem是 CocoaPods，这是一个流行的依赖管理器，用于管理和集成 iOS 项目的第三方库。

一个典型的 Gemfile 文件结构如下：

# 指定 gem 的源，这通常是 `https://rubygems.org`，这是官方的 RubyGems 仓库
source "https://rubygems.org"

# 指定 Ruby 版本
ruby ">= 2.6.10"

# 指定项目所需的 gem 及其版本
gem 'cocoapods', '>= 1.13', '< 1.15'
gem 'activesupport', '>= 6.1.7.5', '< 7.1.0'

# 可以定义不同的组，例如开发环境和测试环境
group :development, :test do
  gem "rspec"
end

安装Android开发工具链

先介绍一个检测工具react-native doctor ，它是 React Native 开发环境中一个非常有用的命令行工具，能帮助开发者检测和修复本机系统中的各种开发工具和依赖项，确保安装正确且版本合适。会检查 Node.js、yarn, Metro,JDK，Android Studio、Android SDK，Xcode 以及其它相关工具，并提供自动修复问题的选项。如果 doctor 无法自动解决问题，它将显示消息和链接，说明如何手动修复此问题。

执行下面的命令，就会开始检查React Native开发依赖的大多数软件和工具是否正确安装且版本正确

npx react-native doctor

这是检查结果，因为笔者已经安装好了各种软件和工具，所以只有一项是打叉的。这一项打叉是因为没有在Android Studio中启动模拟器。

要在PC端运行一下Android应用，如果你是初学者，百分之百会遇到一些跟Android平台相关的专业名词如JDK、Android Studio,Android SDK，Gradle、Gradlew，不知道这些名称概念的含义的话，就算效果运行正确，也不代表你会了。别人对你谈起这些名词，你会感觉一头雾水，不知所以然, 无法与别人交流。所以我们先夯实一下基础,了解一下这些名词概念。

在 React Native 和 Android 开发中，JDK、Android Studio、Android SDK 和 Gradle 是几个核心组件，它们之间相互关联，为开发和构建 Android 应用提供完整的支持。它们各自的功能和彼此的关系如下：

JDK (Java Development Kit)

• 功能：JDK 是开发 Java 应用的核心工具包，包含了 Java 编译器（javac）、Java 运行时环境（JRE）以及其他工具。
• 关系：JDK 是编译和构建 Android 应用的必要工具，因为 Android 应用开发和 Gradle 构建工具需要使用 Java 编写的脚本和配置文件。

Android Studio

• 功能：Android Studio 是 Android 应用开发的官方集成开发环境（IDE），提供了代码编辑、调试、测试和构建等一站式解决方案。
• 关系：Android Studio 包含了 Android SDK、Gradle 插件和其他开发工具，简化了应用开发和构建过程。它也需要依赖 JDK 来运行和编译项目。

Android SDK (Software Development Kit)

• 功能：Android SDK 提供了开发 Android 应用所需的所有工具和 API，包括模拟器、调试工具和平台库。
• 关系：Android SDK 是 Android Studio 的一部分，但也可以独立安装。开发者通过 Android SDK 访问设备和平台功能，在应用中使用这些功能。

Gradle and Gradlew

• Gradle：
• 功能：Gradle 是一个灵活的构建自动化工具，主要用于项目构建、依赖管理和部署。它支持多种编程语言和项目类型。
• 关系：在 Android 开发中，Gradle 通过 Android 插件支持编译、打包和测试应用。Gradle 脚本（build.gradle）用于定义项目的构建逻辑和依赖项。
• Gradlew (Gradle Wrapper)：
• 功能：Gradlew 是 Gradle 的包装器，确保项目使用特定版本的 Gradle 构建，而不依赖于系统中安装的 Gradle 版本。
• 关系：Gradlew 提供了跨平台一致的构建环境。它与项目一起分发，使任何开发者都能使用正确版本的 Gradle 构建项目，而无需手动安装 Gradle。

总结一下就是:

• JDK：提供 Java 编译和运行环境，是构建 Android 应用的基础工具。
• Android Studio：集成开发环境，包含了 Android SDK 和 Gradle 插件，简化了开发和构建过程。
• Android SDK：包含开发 Android 应用所需的所有工具和 API。
• Gradle/Gradlew：构建自动化工具，用于编译、打包和管理项目依赖，Gradlew 确保项目使用特定版本的 Gradle。

它们共同构成了 Android 应用开发和构建的完整工具链，相互依赖且紧密集成。

环境搭建中遇到的问题

1.本地运行时，报JAVA_HOME环境变量找不到

ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.

去Oracle官网，下载win版的jdk安装包 。注意版本jdk版本，doctor提示jdk的版本必须是>=17，<=20, 去官网一看， 只有22,21,17三个版本可以下载，那只能选择jdk17。衍生问题-jdk下载过慢。解决方法： 将下载链接的协议头由https改成http，由于下载时默认是https，所以会慢一些，使用http之后会好很多，速度能稳定在400k左右，十分钟之内就可以下完，速度还可以。另外，配置JAVA_HOME环境变量的时候，路径后面不能带bin。

2. Android Studio软件在国内无法下载

安装Android Studio时，直接搜索Android Studio下载地址，去官网下载，发现国内用户直接下载不了。访问这个地址，界面的语言默认是英文，却可以正常下载，默认打开的Android Studio页面语言是中文的话，就下载不了。莫非是美国佬不让大陆开发者使用Android Stduio.

3.找不到模拟器Failed to launch emulator. Reason: No emulators found as an output of emulator -list-avds？

安装好Android Studio之后，需要创建一个模拟器。就不会报这个错误了。Android模拟器查看和启动方法

emulator -list-avds
emulator -avd 模拟起名称

4.JDK已安装，用react-native doctor检查的时候，报未安装

用 java -version命令查看发现返回为空，是因为安装了两个版本的JDK所致。一个是本次在Android Studio安装中，一个是以前手动安装的。要删除一个。删除jdk时，搜索的应用名称应该是Java，此外，手动删除JDK的安装目录文件，是不行的，必须用系统的软件卸载功能进行卸载。

5. Android Studio已安装，执行react-native doctor命令，提示未安装

安装Android Studio时不要自定义安装路径，安装到默认路径。

6. 执行react-native run-android,抛错 Exception in thread "main" java.io.IOException: Downloading from https://services.gradle.org/distributions/gradle-8.6-all.zip failed: timeout (10000ms)?

出现这个报错是因为下载gradle-8.6-all.zip包超时引起的，可以修改一下项目根目录下的 android\gradle\wrapper\gradle-wrapper.properties文件配置，把gradle的下载路径改成本地路径，然后手动下载这个压缩包，放到配置的本地路径中。

distributionUrl=gradle-8.6-all.zip

7. 运行抛错java.io.UncheckedIOException: Could not move temporary workspace (项目路径XXX\android\.gradle\8.6\dependencies-accessors\423f0288fa7dffe069445ffa4b72952b4629a15a-c90c8f8d-2e55-4686-acd5-6452418d6048) to immutable location (项目路径XXX\android\.gradle\8.6\dependencies-accessors\423f0288fa7dffe069445ffa4b72952b4629a15a)

这个错误的意思是在 Gradle 构建过程中，尝试将临时工作空间移动到最终位置时出错,错误原因通常与文件系统权限或路径问题有关。默认配置下载的gradle-8.6-all.zip会报这个错误，将gradle工作包降级为gradle-8.5-bin.zip后，此问题消失。

distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-bin.zip

8. 卸载Android Studio之后，再次安装打开后，不提示SDK安装弹窗，手动安装SDK的方法

操作菜单路径 File==> Settings==> Languages & Frameworks==>Android SDK==>Edit，如下图所示。

SDK安装目录为：

C:\Users\Administrator\AppData\Local\Android\Sdk

9. 报配置文件中引用的@react-native-community/cli-platform-android @react-native/gradle-plugin npm包不存在

如果用pnpm安装会出现这个问题，用yarn安装则不会，因为yarn会安装自动隐式依赖。

Settings file 'D:\juejin-main\android\settings.gradle' line: 2 apply from: file("../node_modules/@react-native-community/cli-platform-android/native_modules.gradle"); applyNativeModulesSettingsGradle(settings) Could not read script '项目路径\node_modules@react-native-community\cli-platform-android\native_modules.gradle' as it does not exist.

补充安装这两个包

pnpm add -D  @react-native-community/cli-platform-android @react-native/gradle-plugin

10. NDK（Native Development Kit）未安装报错

What went wrong: A problem occurred configuring project ':react-native-screens'. [CXX1101] NDK at C:\Users\Administrator\AppData\Local\Android\Sdk\ndk\26.1.10909125 did not have a source.properties file

Android NDK（Native Development Kit）是一个工具集，允许开发者使用 C 和 C++ 代码来构建 Android 应用程序的一部分。NDK 提供了构建和打包原生代码的工具和库，帮助开发者创建高性能的应用程序，尤其是在涉及到计算密集型任务时，如游戏、图形处理和信号处理等。

通过 Android Studio 安装 NDK，操作步骤：

1. 打开 Android Studio。
2. 选择 SDK Manager（工具栏上的小安卓图标）。
3. 在 SDK Manager 中，选择 SDK Tools 选项卡。
4. 勾选 NDK (Side by side) 和 CMake。
5. 点击 Apply 并等待下载和安装完成。

注意下载版本要与报错的NDK版本保持一致。

11. 运行react-native run-android,发现会下载许多jar包，如果某个jar包下载超时，就会导致程序中途退出。

解决方法:修改项目下的android\build.gradle项目依赖项的像源地址。添加阿里云镜像地址，并配置在前面，优先使用。

buildscript {
    // 定义了 Gradle 构建脚本所需的依赖项应该从哪些存储库中获取。常见的存储库有 `google()` 和 `mavenCentral()`。
    repositories {
      
        maven { url "https://maven.aliyun.com/repository/public" }
        maven { url "https://maven.aliyun.com/nexus/content/repositories/jcenter" }
        maven { url "https://maven.aliyun.com/nexus/content/repositories/google" }
        google()
        jcenter()
        mavenCentral()
    }
    // ...
}

allprojects {
    // 定义了所有子项目在解析依赖项时使用的存储库
    repositories {
        maven { url "https://maven.aliyun.com/repository/public" }
        maven { url "https://maven.aliyun.com/nexus/content/repositories/jcenter" }
        maven { url "https://maven.aliyun.com/nexus/content/repositories/google" }
        google()
        jcenter()
        mavenCentral()
    }
}
apply plugin: "com.facebook.react.rootproject"

最后

没动手实践之前，本以为依葫芦画瓢，能很快把效果做出来。实际在做的时候，发现自己把这件事想得简单了。在运行项目的过程中，出现了许多报错，上面的这些问题我把解决方法都记录下来了，有些也遗漏了。我踩过的坑，希望你看完这篇文章之后，就不要再重蹈覆辙了。这样才能体现出你阅读本文的价值。还有就是看完一篇技术文章，不能看一看就觉得自己会了，最好动手做一做。有许多潜在的技术问题在看的过程中是无法暴露出来的，你以为你会了，实操的时候还是会遇到一大堆问题，平时有时间的话要提前扫雷, 这样将来遇到相关问题时就不会手忙脚乱。

原文：https://juejin.cn/post/7382891974942048282