Rork React Native ビルドエラー完全解決ガイド 2026

Rork で React Native アプリを開発するとき、最も遭遇しやすいのがビルドエラーです。 Metro Bundler が起動しない、Android の Gradle ビルドが失敗する、iOS の Xcode エラー、Expo 設定の不整合……。

これらのエラーは、ネイティブ開発の経験が浅いと「何が悪いのか」さえ分からず、試行錯誤に陥りやすいです。このガイドでは、Rork で生成されたコードに基づきながら、ビルドエラーの原因を素早く特定し、段階的に解決するステップ を詳しく解説します。

ビルドエラーの診断フローチャート

ビルドエラーに遭遇したら、以下のフローに沿って原因を特定してください。

1. "npm start" でエラー? → Metro Bundler の問題
   ├─ "Cannot find module" → 依存関係の欠落
   ├─ "Address already in use" → ポート競合
   ├─ "Error: ENOSPC" → ディスク容量不足
   └─ "Syntax error" → JavaScript コードのエラー

2. "npm run android" でエラー? → Gradle/Android ビルド問題
   ├─ "FAILURE: Build failed" → Gradle 設定
   ├─ "Could not find" → 依存パッケージ
   └─ "Target API level" → Gradle.properties 設定

3. "npm run ios" でエラー? → Xcode/iOS ビルド問題
   ├─ "No such module" → Pod インストール漏れ
   ├─ "Multiple commands produce" → ビルド設定競合
   └─ "Code signing" → プロビジョニング証明書

4. アプリが起動しない（ビルドは成功）? → ランタイムエラー
   ├─ "Red screen of death" → JavaScript 実行時エラー
   └─ "Native crash" → ネイティブコードの問題

エラー 1: Metro Bundler が起動しない

症状

npm start

を実行すると、以下のエラーが表示される：

Error: Failed to load /path/to/metro.config.js
Cannot find module 'metro'

原因

node_modules が存在しない、または破損している
Metro CLI の依存パッケージが不足している
package.json と package-lock.json に不整合がある

解決策

# Step 1: node_modules を全削除
rm -rf node_modules package-lock.json
 
# Step 2: 再インストール（npm キャッシュもクリア）
npm cache clean --force
npm install
 
# Step 3: Expo で管理している場合
expo prebuild --clean
 
# Step 4: Metro キャッシュをクリア
rm -rf /tmp/metro-*
rm -rf $TMPDIR/metro-*  # macOS
 
# Step 5: 起動
npm start

エラー 2: "Address already in use" — ポート競合

症状

Starting Metro Bundler
> listening on port 8081
Error: listen EADDRINUSE: address already in use :::8081

原因

別のプロセスが ポート 8081 を使用しているため、Metro Bundler が起動できません。

解決策

# 現在ポート8081を使用しているプロセスを確認
lsof -i :8081
 
# 例：
# COMMAND   PID   USER   FD   TYPE    DEVICE SIZE/OFF NODE NAME
# node    12345   user   25u  IPv6 0x12345678      0t0  TCP *:8081 (LISTEN)
 
# プロセスを強制終了
kill -9 12345
 
# または、別のポート を使用
npm start -- --port 8082
 
# 次に、Expo/React Native CLI も別ポートで起動を指定
REACT_NATIVE_DEBUGGER_PORT=8082 npm run android

エラー 3: "Cannot find module" — 依存関係の欠落

症状

Error: Cannot find module '@react-navigation/native'

原因

package.json に記載されていない
npm install 時にダウンロード失敗
Rork が生成したコードで使っているモジュールがインストール漏れ

解決策

# 不足しているモジュールをインストール
npm install @react-navigation/native @react-navigation/bottom-tabs
 
# または、package.json を確認して修正
cat package.json | grep dependencies -A 20
 
# さらに、Rork が推奨する依存パッケージをすべて追加
# （Rork の生成スキップで --skip-install を使った場合）
npm install --save-exact
 
# ネイティブリンクが必要なモジュールの場合
npx react-native link

エラー 4: Gradle ビルド失敗（Android）

症状 A: "FAILURE: Build failed with an exception"

FAILURE: Build failed with an exception.

* What went wrong:
Could not resolve all dependencies for configuration ':app:debugRuntimeClasspath'.
> Could not find com.facebook.react:react-native:0.xx.x

原因

Android SDK がインストールされていない
Gradle のバージョン不整合
ネイティブモジュールの依存関係が解決されていない

解決策

# Step 1: 環境変数を確認
echo $ANDROID_HOME
# 出力がない場合は、Android SDK をインストール
 
# macOS の場合
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools
 
# Step 2: gradle.properties を確認・修正
cat android/gradle.properties

gradle.properties の推奨設定：

# Android SDK バージョン
android.useAndroidX=true
android.enableJetifier=true
org.gradle.jvmargs=-Xmx2g -XX:MaxPermSize=512m
org.gradle.parallel=true
 
# React Native バージョンに合わせる
REACT_NATIVE_VERSION=0.73.0
ANDROID_SDK_VERSION=34

# Step 3: Gradle キャッシュをクリア
rm -rf android/.gradle
 
# Step 4: 再ビルド
npm run android

症状 B: "Target API level mismatch"

The minSdkVersion should be minimum 21

解決策

# android/build.gradle を編集
cat android/build.gradle

buildscript {
    ext {
        buildToolsVersion = "34.0.0"
        minSdkVersion = 21        # ← 最小値
        compileSdkVersion = 34    # ← 最新値
        targetSdkVersion = 34
    }
}

エラー 5: Xcode ビルド失敗（iOS）

症状 A: "No such module 'FBReactNativeSpec'"

Build failed: No such module 'FBReactNativeSpec'

原因

iOS の CocoaPods のインストールが完了していません。

解決策

# Step 1: Pods をクリア
rm -rf ios/Pods ios/Podfile.lock
 
# Step 2: Pod 再インストール
cd ios
pod install --repo-update
cd ..
 
# Step 3: Xcode のビルドキャッシュをクリア
xcodebuild clean -workspace ios/{ProjectName}.xcworkspace \
  -scheme {ProjectName}
 
# Step 4: 再ビルド
npm run ios

症状 B: "Multiple commands produce"

error: Multiple commands produce 'Build/Intermediates.noindex/...'

原因

Xcode のビルド設定に重複があります。

解決策

# ios/{ProjectName}.xcodeproj/project.pbxproj を確認
grep -n "path.*\.m\|path.*\.swift" ios/{ProjectName}.xcodeproj/project.pbxproj
 
# または、Xcode GUI で：
# Build Phases → Compile Sources で重複を削除

症状 C: "Code signing" エラー

Code Signing Error: "iPhone Developer" identity does not exist

原因

Apple 開発者証明書がインストールされていません。

解決策

# Step 1: インストール済みの証明書を確認
security find-identity -v -p codesigning
 
# Step 2: Xcode に証明書をインポート
# Xcode Preferences → Accounts → Apple ID でログイン
 
# Step 3: Signing & Capabilities タブで Team を選択
# （Xcode GUI での操作）

エラー 6: Expo 設定の不整合

症状

Error: Cannot find module 'expo'
// または
Error: Expo CLI version mismatch

原因

Rork が Expo を前提としていますが、expo CLI がインストール漏れ
package.json の Expo バージョンと実際にインストールされたバージョンが異なる

解決策

# Step 1: Expo をグローバルでインストール
npm install -g expo-cli
 
# Step 2: プロジェクト内の Expo をアップデート
npm install expo@latest
 
# Step 3: Expo config を確認
cat app.json

app.json の正しい形式（Rork 推奨）：

{
  "expo": {
    "name": "My App",
    "slug": "my-app",
    "version": "1.0.0",
    "orientation": "portrait",
    "icon": "./assets/icon.png",
    "splash": {
      "image": "./assets/splash.png",
      "resizeMode": "contain",
      "backgroundColor": "#ffffff"
    },
    "ios": {
      "supportsTabletMode": true
    },
    "android": {
      "adaptiveIcon": {
        "foregroundImage": "./assets/adaptive-icon.png"
      }
    },
    "web": {
      "favicon": "./assets/favicon.png"
    }
  }
}

# Step 4: 再起動
npm start

エラー 7: JavaScript ランタイムエラー（Red Screen）

症状

ReferenceError: Can't find variable: __dirname

またはアプリが起動直後に赤い画面（Red Screen of Death）が表示されます。

原因

Node.js グローバル変数の使用（__dirname, __filename, process 等）
サーバー専用モジュールの使用（fs, path 等）
タイポやモジュール指定の誤り

解決策

// ❌ NG: Node.js 専用
const path = require('path');
const filePath = __dirname + '/data.json';
 
// ✅ OK: React Native 対応
import { getAssets } from 'react-native-fs';
 
getAssets().then(assets => {
  // Assets を取得
});

# また、android/gradle.properties で以下を確認
org.gradle.jvmargs=-Xmx2g -XX:+UseG1GC -XX:MaxGCPauseMillis=200

エラー 8: ネイティブモジュールリンク失敗

症状

error: No matching constructor for initialization of 'java.lang.Exception'

または iOS で Bridging Header が見つからないエラー。

原因

Rork が自動生成したネイティブモジュール（Swift/Kotlin コード）が、プロジェクトのビルド設定と合致していません。

解決策

# 自動リンクを再実行
npx react-native link
 
# または、手動でリンク設定を確認（iOS）
ls -la ios/Podfile
cat ios/Podfile | grep post_install

問題がある場合は、該当する CocoaPod を手動で指定：

cd ios
pod deintegrate
pod install --repo-update
cd ..

デバッグのベストプラクティス

エラーメッセージを全文読む — 最初の 1 行だけでなく、stack trace 全体を確認
Metro Bundler のログを見張る — npm start の出力にヒントがある
キャッシュを疑う — node_modules, Pods, .gradle が壊れていることが多い
バージョンを統一する — React Native, Expo, Node.js のバージョンマトリックスを確認
ローカル環境を記録する — .env.example に環境変数をテンプレート化
EAS Build を活用する — ローカルトラブル回避用として有効

全体を振り返って

Rork で React Native アプリのビルドエラーに遭遇したら、以下の優先順序で対処してください：

キャッシュをクリア（node_modules, Pods, .gradle）
依存パッケージを再インストール（npm ci）
ネイティブビルド設定を確認（gradle.properties, Podfile）
Expo / React Native CLI バージョンを統一
デバッグ出力を確認（verbose オプション）
必要に応じて EAS Build を検討

このガイドで網羅していない症状に遭遇した場合は、Rork 公式ドキュメントや React Native 公式 Troubleshooting を参照してください。