React Native Gradleビルドエラー「Unresolved reference 'serviceOf'」の解決法

問題の概要

React NativeプロジェクトをGradle 8.10にアップデート後、以下のビルドエラーが発生します：

e: .../node_modules/@react-native/gradle-plugin/build.gradle.kts:10:49: Unresolved reference: serviceOf
e: .../node_modules/@react-native/gradle-plugin/build.gradle.kts:54:11: Unresolved reference: serviceOf

FAILURE: Build failed with an exception.

* Where:
Build file ... line: 10

* What went wrong:
Script compilation errors:
  Line 10: import org.gradle.configurationcache.extensions.serviceOf
                                                           ^ Unresolved reference: serviceOf

このエラーは@react-native/gradle-plugin内のKotlinスクリプト(build.gradle.kts)で未解決の参照serviceOfが発生しています。Gradle 8.10のアップデートによる非互換変更が原因で、同じプロジェクトが開発者環境で動作しても別環境では失敗することもあります。

エラーの背景

serviceOfメソッドはGradleの内部APIで、バージョン8.10で非推奨化・削除されました。React Nativeの一部バージョンがこのAPIに依存しているため発生します。

根本解決策: 公式パッチの適用

最も確実な解決法はReact Native公式リポジトリの修正パッチを適用することです。

手順

1. node_modules/@react-native/gradle-plugin/build.gradle.ktsを開く
2. 以下の変更を適用:

// 修正前（エラーの原因となる行）
import org.gradle.configurationcache.extensions.serviceOf

// ...
project.extensions.configure<ReactExtension> {
    // ...
    dependencyAliases = serviceOf<ModuleRegistry>()
        .getModule()
        .getDependencyAliases()
}

// 修正後（サービス参照を更新）
import org.gradle.api.internal.project.ProjectInternal

// ...
project.extensions.configure<ReactExtension> {
    // ...
    val projectInternal = project as ProjectInternal
    dependencyAliases = projectInternal.services
        .get(ModuleRegistry::class.java)
        .getDependencyAliases()
}

3. patch-packageで変更を永続化

npx patch-package @react-native/gradle-plugin

4. プロジェクト再構築

npm run android  # または ./gradlew clean && ./gradlew assembleDebug

patch-packageについて

• 変更をpatchesディレクトリに保存し、毎回npm install後に自動適用
• 初回実行前にインストール: npm install patch-package --save-dev
• package.jsonのpostinstallスクリプトに追加推奨:

"scripts": {
    "postinstall": "patch-package"
}

代替解決策（一時的な回避法）

1. gradle-pluginの依存バージョン固定

android/build.gradleで明示的にバージョンを指定:

dependencies {
    classpath("com.android.tools.build:gradle:8.4.0")
    // バージョン0.75.4以降には修正が含まれる
    classpath("com.facebook.react:react-native-gradle-plugin:0.75.4") 
    classpath("com.google.gms:google-services:4.4.0")
    classpath("org.jetbrains.kotlin:kotlin-gradle-plugin")
}

2. 完全クリーンインストール

パッチ適用前の一時的対策:

# キャッシュと依存関係を完全削除
rm -rf node_modules package-lock.json android/.gradle

# 依存関係再構築
npm install
npm dedupe

# Gradleキャッシュクリーン
cd android && ./gradlew clean

3. ワークアラウンド（非推奨）

noinspectionでエラーを無視（一時的回避）:

@Suppress("DEPRECATION")
import org.gradle.configurationcache.extensions.serviceOf

// ...

project.extensions.configure<ReactExtension> {
    @Suppress("UnstableApiUsage")
    dependencyAliases = serviceOf<ModuleRegistry>()
        .getModule()
        .getDependencyAliases()
}

注意事項

この方法はビルドを通すだけの応急処置です。将来のGradleアップデートで完全に機能しなくなる可能性があります。

環境設定チェックリスト

全ての開発環境で一貫性を保つために確認すべき設定：

1. Gradle Wrapper (gradle-wrapper.properties)

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

2. Androidビルドツール (android/build.gradle)

ext {
    buildToolsVersion = "34.0.0"
    minSdkVersion = 23
    compileSdkVersion = 34
    targetSdkVersion = 34
    ndkVersion = "25.1.8937393"
    kotlinVersion = "1.8.0"  // Kotlinバージョン整合性確認
}

3. Node.jsバージョン

// package.json
"engines": {
    "node": ">=16"
}

4. プロジェクト共通化

• gradle/wrapper/gradle-wrapper.jarをバージョン管理に含める
• .tool-versionsや.nvmrcでNodeバージョン固定

トラブルシューティング

パッチ適用後もエラーが解決しない場合の対応：

1. キャッシュの多重構造を確認

# Android Studioキャッシュ削除
rm -rf ~/.gradle/caches

2. Kotlinプラグインの整合性チェック

// android/build.gradle
buildscript {
    dependencies {
        // Kotlinバージョンを明示的に指定
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:1.8.0")
    }
}

3. React Nativeコミュニティが公式修正をリリースしていないか確認

npm view @react-native/gradle-plugin versions --json

まとめ

ビルドエラー「Unresolved reference 'serviceOf'」は、修正パッチの適用が最も確実な解決法です。公式リポジトリのPR #46367に従い、patch-packageで変更を管理しましょう。

ベストプラクティス

• チーム開発ではpatchesディレクトリをリポジトリにコミット
• 定期的に依存ライブラリを更新し、不要なパッチを削除
• Gradleプロパティで警告表示を有効化: ./gradlew build --warning-mode=all

最終的にはReact Nativeが正式バージョンで修正するまで、これらの作業を含む「アップグレード作業手順」をチームで共有することが重要です。