React Native 0.73.9 升级 Gradle 8.10 后 'serviceOf' 引用错误

问题描述

升级 Gradle 到 8.10 后，构建 React Native 0.73.9 项目时出现 Unresolved reference: serviceOf 错误，导致构建失败。错误信息如下：

// 错误输出示例
e: file:///path/to/node_modules/@react-native/gradle-plugin/build.gradle.kts:10:49: 
Unresolved reference: serviceOf

FAILURE: Build failed with an exception.

* Where:
Build file 'node_modules/@react-native/gradle-plugin/build.gradle.kts' line: 10

* What went wrong:
Script compilation errors:

  Line 10: import org.gradle.configurationcache.extensions.serviceOf
                                                           ^ Unresolved reference: serviceOf

该问题在升级到 Gradle 8.10 并配合 React Native 0.73.9 使用时出现，具体原因是 Gradle 8.10 中移除了 serviceOf 方法，但 React Native Gradle 插件尚未适配此变更。

环境说明

• React Native 版本: 0.73.9
• Gradle 版本: 8.10
• Gradle 插件: com.android.tools.build:gradle:8.4.0
• 错误文件路径: node_modules/@react-native/gradle-plugin/build.gradle.kts

解决方案

临时修复方法（推荐）

核心解决方案是手动修改 @react-native/gradle-plugin 中的代码，移除对已废弃 serviceOf 方法的引用：

修改步骤

1. 打开文件：
   node_modules/@react-native/gradle-plugin/build.gradle.kts

2. 定位到第 10 行，将：
   import org.gradle.configurationcache.extensions.serviceOf
   修改为：
   import org.gradle.internal.buildservices.BuildServices

3. 定位到第 54 行附近，将：
   val moduleRegistry = serviceOf<ModuleRegistry>()
   修改为：
   val moduleRegistry = project.services.get()

修改后示例

// build.gradle.kts 修改部分
// 修改前
import org.gradle.configurationcache.extensions.serviceOf

// ... 省略 ...
val moduleRegistry = serviceOf<ModuleRegistry>()

// 修改后
import org.gradle.internal.buildservices.BuildServices

// ... 省略 ...
val moduleRegistry = project.services.get()

使用 patch-package 持久化修复

为防止 npm install 后修改被覆盖，建议使用 patch-package 保存修改：

安装 patch-package

# 安装依赖
npm install patch-package --save-dev

生成补丁

# 1. 完成上述手动修改后执行
npx patch-package @react-native/gradle-plugin

# 2. 在 package.json 中添加 postinstall 脚本
{
  "scripts": {
    "postinstall": "patch-package"
  }
}

其他注意事项

1. 依赖清理：修改前先清除缓存

   rm -rf node_modules
   rm -rf android/.gradle
   npm install

2. Gradle 版本验证：确认 gradle-wrapper.properties 中版本正确

   distributionUrl=https\://services.gradle.org/distributions/gradle-8.10-all.zip

3. Android 构建配置

   // android/build.gradle 参考配置
   buildscript {
      ext {
          buildToolsVersion = "34.0.0"
          minSdkVersion = 23
          compileSdkVersion = 34
          targetSdkVersion = 34
          kotlinVersion = "1.8.0"
      }
   }

原理解析

此错误源于 Gradle 8.10 的 API 变更：

1. 废弃 serviceOf 方法：Gradle 8.10 移除了 serviceOf 扩展函数
2. React Native 插件兼容问题：@react-native/gradle-plugin 0.75.3 尚未适配此变更
3. 解决方案本质:
   • 从 BuildServices 中获取服务注册
   • 通过 project.services.get() 直接访问服务
4. patch-package 作用：将对 node_modules 的修改保存为补丁，在每次安装后自动应用

该修复已在 React Native 主分支中提交（参考 PR #46367），后续版本将包含此修复。

预防措施

1. 关注 React Native 版本更新
2. 升级前检查 GitHub issue 中的已知问题
3. 使用 CI/CD 时在脚本中添加缓存清理步骤

替代方案

若上述方法无效，可考虑：

1. 降级 Gradle（不推荐）

   distributionUrl=https\://services.gradle.org/distributions/gradle-8.0-all.zip

2. 更新 React Native（需验证兼容性）

   npm install react-native@0.74.0

建议优先使用 patch-package 方案，它能在保持当前环境稳定的同时解决问题。