如何修复 React Native 中的所有构建错误（特定于 Android）。

2025-06-10

如何修复 React Native 中的所有构建错误（特定于 Android）。

刚开始用 React Native 开发 Android 应用时，我对这个框架非常失望，几乎放弃了。因为每次尝试用它编译应用，npx react-native run-android都会遇到一大堆错误。花了好几天时间在 Google 上搜索和阅读 Stack Overflow 的帖子，才修复了一个错误，却又引发了另一组错误，这些错误又需要几天时间才能解决，如此反复，直到你最终放弃，或者应用奇迹般地编译通过。这简直是一场噩梦。

在本文中，我将向您展示如何避免我遇到的所有错误，以及如何在使用 React Native 开发应用程序时遇到它们时避免或修复它们。

1. 务必阅读软件包的文档或其 npm 仓库页面，了解如何正确安装软件包

这是使用 React-Native 构建应用时常见的错误。有时，你没有时间仔细阅读安装和设置包的步骤，因此匆匆浏览安装指南，最终错过了将包与你正在使用的平台集成所需的重要步骤。

React Native 会将代码编译到特定的原生平台上。这意味着，有时为了使某个包能够兼容某个平台（例如 Android），你需要对原生代码和构建工具进行一些修改。

让我们以一个流行的框架 react-native-vector-icons 为例，它是一个库，允许你在一处使用来自不同矢量图标工具包的矢量图标，包括 FontAwesome、Ionicons、MaterialIcons、AntDesign 等等。你可以使用以下命令安装此包：



npm install react-native-vector-icons
Enter fullscreen mode Exit fullscreen mode

然后你就可以开始使用这个库了吗？嗯……还不完全是。如果你只做了这些，那就准备好迎接一些棘手的错误和挫折吧。正如你在https://www.npmjs.com/package/react-native-vector-icons中看到的，如果你是为 iOS 构建，你需要在 Xcode 中做一些更改；如果你想让这个包适用于 Android 平台，你还需要对 android 文件夹中的文件进行一些更改。具体来说，对于 Android 平台，你需要更改以下文件：



android/app/build.gradle 
android/app/src/main/assets/fonts 
android/settings.gradle 
android/app/src/main/java/<your_android_app_package_name>/MainApplication.java
Enter fullscreen mode Exit fullscreen mode

如上面的链接所述。

设置过程可能相当繁琐，但严格按照步骤进行将会为您省去很多麻烦。

有些软件包需要你安装其他软件包才能正常工作。例如，@react-navigation/native 库https://reactnavigation.org/docs/getting-started/，它需要你安装 react-native-screens 和 react-native-safe-area-context。但在 Android 设备上，react-native-screens 需要你进行配置android/app/src/main/java/<your_android_app_package_name>/MainActivity.java，将以下内容添加到 MainActivity 类中：



@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(null);
}
Enter fullscreen mode Exit fullscreen mode

并要求您在该文件顶部添加导入语句：



import android.os.Bundle;
Enter fullscreen mode Exit fullscreen mode

然后您才可以开始在项目中使用该库。

基本上，你安装的任何库



npm install <package-name>
Enter fullscreen mode Exit fullscreen mode

确保您找到并遵循该包的安装说明。

此外，如果您最终需要更新软件包，或者您正在创建一个新的 react-native 应用程序并决定使用较新版本的软件包，请确保检查是否有重大更改，并检查是否需要其他步骤才能使新版本正常工作。

2. 此版本中使用了已弃用的 Gradle 功能，导致其与 Gradle 7.3 不兼容（或其他 Gradle 版本中出现类似错误）

npx react-native init <Project-name>基本上，这个错误是想告诉你，这个特定的软件包不支持你用于 Android 构建的 Gradle 版本。如果你曾经生成过新的 React Native 应用，那么每个人都可能遇到过这个错误。

为什么会发生这个错误？

发生这种情况是因为react-native init始终将最新版本的 Gradle 运送到您的 android 项目，而第三方库可能不支持该 Gradle 版本，从而导致您的 Gradle 版本与该库不兼容。

您需要做的是为您的项目安装早期版本的 Gradle，然后重建您的应用程序。

步骤 1：安装早期版本的 Gradle

要查看你的 Gradle 版本，请转到项目的 android 文件夹并输入gradlew -v：



cd android
gradlew -v
Enter fullscreen mode Exit fullscreen mode

前往https://developer.android.com/studio/releases/gradle-plugin。向下滚动到“更新 Gradle”部分。在这里，你会看到 Gradle 版本和插件版本的表格。

图片描述

如您所见，在撰写本文时，最新的 Gradle 版本是 7.3+，相关插件版本是 7.2。

通常，我通常会选择距离最新版本 3 级的 Gradle 版本。在本例中，Gradle 版本是 6.7.1+，对应的插件版本是 4.2.0+。您可以选择最适合您的 Gradle 版本。

图片描述

现在，android/build.gradle在文本编辑器中打开。你会看到如下内容：



buildscript {
...
dependencies {
classpath("com.android.tools.build:gradle:7.2.0")
// NOTE: Do not place your application dependencies here; they belong
// in the individual module build.gradle files
}
}
Enter fullscreen mode Exit fullscreen mode

classpath("com.android.tools.build:gradle:7.2.0") 的形式为 classpath("com.android.tools.build:gradle:")。

因此，将插件版本更改为您从上表中选择的版本。此行现在是：



classpath("com.android.tools.build:gradle:4.2.0")
Enter fullscreen mode Exit fullscreen mode

在文本编辑器中打开android/gradle/warpper/gradle-wrapper.properties。你会看到类似这样的内容：



distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-7.3.0-all.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists
Enter fullscreen mode Exit fullscreen mode

我们对以下产品感兴趣distributionUrl=https\://services.gradle.org/distributions/gradle-7.3.0-all.zip

这一行的形式是



distributionUrl=https\://services.gradle.org/distributions/gradle-<gradle-version>-all.zip
Enter fullscreen mode Exit fullscreen mode

更改 Gradle 版本以匹配您选择的插件版本。完成后，此行应如下所示：



distributionUrl=https\://services.gradle.org/distributions/gradle-6.7.1-all.zip
Enter fullscreen mode Exit fullscreen mode

第 2 步：重建应用程序

从您的项目文件夹运行以下命令：



rm -r android/build ; rm -r android/app/src/release/res ; rm -r android/app/build/intermediates
Enter fullscreen mode Exit fullscreen mode

此命令所做的就是通过删除包含它们的文件夹来删除应用程序的先前版本。如果您愿意，可以手动删除文件夹：android/build, android/app/src/release/res, android/app/build/intermediates。

完成后，进入 android 文件夹并清理 gradle：



cd android
gradlew clean
Enter fullscreen mode Exit fullscreen mode

确保您现在拥有您指定的 Gradle 版本：



gradlew -v
Enter fullscreen mode Exit fullscreen mode

返回到根项目文件夹并构建应用程序：



cd..
npx react-native run-android
Enter fullscreen mode Exit fullscreen mode

您的应用现在应该可以顺利构建，所有“此构建中使用了弃用的 Gradle 功能”错误都已消失。如果错误仍然存​​在，请尝试更早的 Gradle 版本。但不要尝试太早。

3. java.io.IOException：无法删除路径

有时您会看到类似这样的错误：



* What went wrong:
Execution failed for task ':@myApp/react-native-spinkit:mergeReleaseResources'.
> java.io.IOException: Could not delete path 'C:\Users\My\Desktop\App\node_modules\@myApp
\react-native-spinkit\android\build\intermediates\res\merged\release\drawable-xhdpi-v4'.
Enter fullscreen mode Exit fullscreen mode

我注意到，当我对 Gradle 进行更改（例如更改 Gradle 版本或更改文件中支持的 Android 版本范围）时，会遇到此类错误android/build.gradle。当进行影响当前 Android 构建的更改时，Gradle 会尝试从旧构建中删除文件并创建新文件。此错误表明其他程序当前正在访问这些文件，并阻止它们被删除。大多数情况下，阻止这些文件删除的是 Metro Bundler。因此，您需要在不运行 Metro 的情况下重新构建。有两种方法可以执行此操作：

  • 方法一：清理 Gradle

运行此代码，确保 Metro 未运行：



cd android
gradlew clean
Enter fullscreen mode Exit fullscreen mode
  • 方法二：手动停止Metro

使用以下方式构建您的应用程序：



npx react-native run-android
Enter fullscreen mode Exit fullscreen mode

当地铁终点站出现时，将其关闭。

应用程序捆绑完成后，npx react-native run-android再次运行。这次，允许 Metro 运行。

您的应用程序现在应该已安装并按预期运行。

4. 由于 JVM（Java 虚拟机）堆空间耗尽，守护进程到期。

当您构建 React Native Android 应用程序时，您可能会遇到错误：堆限制分配失败。当您有很多库并且您的应用程序变得更大时，就会发生这种情况。

此错误主要出现在您使用发布密钥对 Android 应用进行签名并生成发布 AAB 以上传到 Google Play 商店后。

要解决这个问题，您必须增加堆内存分配。

为此，请android/gradle.properties在文本编辑器中打开该文件并将以下行添加到末尾：



org.gradle.daemon=true
org.gradle.jvmargs=-Xmx4g -XX:MaxPermSize=2048m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8
Enter fullscreen mode Exit fullscreen mode

然后在文本编辑器中打开该文件android/app/build.gradle。在 android 任务下添加以下内容：



android {
...
  dexOptions {
    javaMaxHeapSize "4g"
  }
...
}
Enter fullscreen mode Exit fullscreen mode

您的应用程序现在应该可以顺利构建并且不会出现任何错误。

这些错误是 React-native Android 构建失败的根源。修复这些问题可以让你避免许多由碎片化解决方案引发的错误。

如果您仍然像我一样遇到这些错误，或者希望使用 React Native 开始 Android 应用程序开发，我希望这将为您节省大量时间、压力和精力，让您更好地投入到富有成效的工作中。

鏂囩珷鏉ユ簮锛�https://dev.to/stan6453/how-to-fix-all-build-errors-in-react-nativeandroid-specific-241f
Devto 翻译
PREV
Thanos Snap 你的仓库 Thanos Snap
NEXT
Angular 面试题（第三部分）