React Nativeでよくあるビルドトラブルとその対処

こんにちは、Takagiです。
弊社では自社プロダクト「VeriCerts」を含め、アプリ開発にReact Nativeを採用しています。
iOSとAndroidを（ほぼ）統一したソースコードで管理できるのはクロスプラットフォームの強みですが、
その複雑さゆえに環境由来のエラーが膨大なのも事実。
実際、私もエラーで1日が溶けるなんてザラでした。
本稿では過去の私がメモとして残していたエラーをビルドがこけたときの対処法としてまとめてみました。
どうか皆さんが無駄な時間に足を取られず、
ストレスフリーな開発ライフを送れることを祈ります。

---

1. iOS ビルドがこける系のやつ

1‑1. [CP‑User] [Hermes] Replace hermes for the React Native で Pod install が停止

原因
Hermes の Pod キャッシュや Podspec の不整合。（おそらく）

対処

# 1) キャッシュと Pods を掃除
rm -rf ios/Pods ~/Library/Caches/CocoaPods

# 2) Pod リポジトリを更新
pod repo update

1-2. Command PhaseScriptExecution failed with a nonzero exit code

原因
ios/.xcode.env.local に古い Node パスが残り、Xcode が存在しない Node を参照している。

対処

cd ios
rm .xcode.env.local
pod install

その後 Xcode を再起動し、DerivedData をクリーンして再ビルド。

---

1-3. # Xcode 16.3&React Native 0.76使用時にシミュレータで落ちる

原因
普通にバグ。(これはわからんって...)

対処
ReactNativeのバージョンを上げる 。
Xcodeのバージョンを上げる。

---

1-4. Typedef redefinition with different types ('uint8_t' …) ― RCT-Folly / Time.h

原因
Xcode 15 以降で発生するバグ。

対処
ReactNativeのバージョンを上げる
発生したらアップグレードが最短。

---

1-5. ld: library not found for -lDoubleConversion

原因
DoubleConversion 静的ライブラリが Xcode の Link Binary Phase に含まれていない、または Cocoapods のビルドフォルダが壊れている。

対処

1. pod deintegrate && pod install で Pods を再構築。
2. Xcode → Build Settings → Library Search Paths に $(inherited) があるか確認。
3. ないなら React-Core/React-Core.xcodeproj を開き、libDoubleConversion.a が Build Phases > Link Binary With Libraries に入っているか確認して追加。

---

2. Android ビルドが失敗する系のやつ

2-1. Gradle could not start your build.

原因
何かしらの原因で前回のビルドプロセスが残り続けている。

対処
gradleのプロセスをkill。

2-2. Duplicate class com.google.firebase.Timestamp

原因
Firebase / Google Play Services の依存バージョンがライブラリごとにズレている。

対処

// android/build.gradle
ext {
  // すべての Firebase 系で同一 BOM を指定
  firebaseBomVersion = "32.7.4"
}

dependencies {
  implementation platform("com.google.firebase:firebase-bom:$firebaseBomVersion")
  // 個別ライブラリはバージョン指定しない
  implementation 'com.google.firebase:firebase-firestore'
}

---

2-3. Execution failed for task ':app:mergeDex…' – 64 K メソッド制限

原因
メソッド数が 65536 を超え、DEX へ分割できていない。

対処

// android/app/build.gradle
android {
  defaultConfig {
    multiDexEnabled true
  }
}

dependencies {
  implementation 'androidx.multidex:multidex:2.0.1'
}

MainApplication.java を MultiDexApplication 継承に変更。

---

補足

• ビルドが通ったら 「原因・対処」 を必ずメモしておくと、未来の自分が助かります。
• この記事は 2025 年 7 月現在の React Native 0.76 系まで検証済みですが、一応公式リリースノートと合わせて確認してください。