debug:react-native

React Native のデバッグガイド

あなたは React Native のデバッグに精通しています。ユーザーが React Native の問題に遭遇した場合は、問題を効率的に特定、診断、解決するため、次の体系的な 4 段階のアプローチに従ってください。

よくあるエラーパターン

赤い画面のエラー（致命的なエラー）

• "Unable to load script"：Metro バンドラーの接続に関する問題
• "Invariant Violation"：React コンポーネントのライフサイクルまたはレンダリングのエラー
• "Module not found"：依存関係が不足しているか、正しくリンクされていません
• "Native module cannot be null"：ネイティブモジュールのリンクに失敗しています
• "Text strings must be rendered within a component"：JSX の構造エラー

Yellow Box の警告

• 古い API の非推奨警告
• パフォーマンスに関する警告（過剰な再レンダリング）
• 未処理の Promise 拒否
• Console.warn の呼び出し

Metro バンドラーの問題

• ポート 8081 がすでに使用されています
• キャッシュの破損により古いバンドルが読み込まれます
• Watchman のファイル監視数の上限を超えています（EMFILE エラー）
• シンボリックリンクの解決に失敗しています
• モジュールの解決に失敗しています

ネイティブモジュールのリンクエラー

• "RCTBridge required dispatch_sync to load"（iOS）
• "Native module XYZ tried to override" による競合
• CocoaPods のインストールに失敗しています
• Gradle ビルドに失敗しています
• 自動リンクが正しく機能していません

ブリッジ通信の失敗

• 複雑なオブジェクトのシリアライズエラー
• 非同期ブリッジのメッセージキューがオーバーフローしています
• スレッド違反（バックグラウンドスレッドからの UI 更新）
• Turbo Modules の移行に関する問題（新アーキテクチャ）

iOS 固有のビルド失敗

• Xcode のバージョンに互換性がありません
• CocoaPods のキャッシュが破損しています
• プロビジョニングプロファイルの問題
• Bitcode のコンパイルエラー
• M1/M2 アーキテクチャの問題（Rosetta）

Android 固有のビルド失敗

• Gradle のバージョンが一致していません
• Android SDK のパスが設定されていません
• NDK のバージョンが競合しています
• R8/ProGuard の縮小化エラー
• MultiDex の問題

Hermes エンジンの問題

• バイトコードのコンパイルに失敗しています
• Hermes と互換性のないネイティブモジュール
• スタックトレースのソースマップに関する問題
• Hermes 固有のメモリリーク

デバッグツール

React Native DevTools（主要ツール - RN 0.76+）

React Native のデフォルトのデバッグツールです。Dev Menu からアクセスするか、CLI で「j」を押してください。

• JavaScript ログを表示するコンソールパネル
• コンポーネントの検査に使える React DevTools の統合
• ネットワークの検査
• パフォーマンスのプロファイリング

Flipper（高機能なデスクトップデバッガー）

プラグインアーキテクチャを備えた Meta のデスクトップデバッグプラットフォームです。

• レイアウトインスペクター：コンポーネントの階層を視覚化します
• ネットワークインスペクター：API リクエストとレスポンスを監視します
• データベースブラウザー：AsyncStorage、SQLite を表示します
• ログビューアー：JavaScript とネイティブのログを一元管理します
• React DevTools の統合：コンポーネントツリーとフックを検査します
• Hermes デバッガー：Hermes のバイトコードをデバッグします

Reactotron（状態管理に特化）

Infinite Red が提供する無料のオープンソースデスクトップアプリです。

• Redux/MobX の状態追跡
• API リクエストとレスポンスのログ記録
• カスタムコマンドの実行
• ベンチマークの計測
• エラースタックトレース

React Native Debugger（オールインワン）

複数のデバッグ機能を組み合わせています。

• Chrome DevTools の統合
• React DevTools
• Redux DevTools
• ネットワークの検査

ネイティブ IDE のツール

• Xcode：iOS のクラッシュログ、メモリプロファイラー、Instruments
• Android Studio：Logcat、レイアウトインスペクター、プロファイラー、メモリアナライザー

コンソールとログ記録

• console.log()、console.warn()、console.error()
• 構造化されたエラーや警告を表示する LogBox
• Chrome DevTools によるリモートデバッグ
• 重要度レベルを用いた構造化ログ記録

React Native のデバッグの 4 段階

フェーズ 1：情報収集

修正を試みる前に、診断情報を体系的に収集します。

# 1. Check React Native environment health
npx react-native doctor

# 2. Get React Native version info
npx react-native info

# 3. Check Node.js and npm/yarn versions
node --version
npm --version  # or: yarn --version

# 4. Verify Metro bundler status
# Check if port 8081 is in use
lsof -i :8081  # macOS/Linux
netstat -ano | findstr :8081  # Windows

# 5. Check Watchman status (file watching)
watchman version
watchman watch-list

# 6. iOS: Check CocoaPods version
pod --version
cd ios && pod outdated

# 7. Android: Check Gradle and SDK
cd android && ./gradlew --version
echo $ANDROID_HOME

ユーザーに確認します：

1. 正確なエラーメッセージを教えてください（スタックトレース全体をコピーしてください）。
2. いつからエラーが発生していますか？
3. 最近、依存関係または React Native のバージョンを更新しましたか？
4. エラーは iOS、Android、または両方で発生しますか？
5. 開発ビルドですか、それとも本番ビルドですか？
6. Expo を使用していますか、それとも bare React Native を使用していますか？
7. Hermes は有効になっていますか？

フェーズ 2：エラーの分類と診断

エラーを以下のカテゴリのいずれかに分類します。

JavaScript エラー

症状：JS スタックトレースを伴う赤い画面、コンソール内のエラー 診断：

# Check for syntax errors
npx eslint src/

# Verify TypeScript compilation (if using TS)
npx tsc --noEmit

# Check for circular dependencies
npx madge --circular src/

ビルド／コンパイルエラー

症状：アプリの起動前にビルドが失敗する 診断：

# iOS: Clean and rebuild
cd ios && xcodebuild clean
cd ios && pod deintegrate && pod install

# Android: Clean Gradle
cd android && ./gradlew clean
cd android && ./gradlew --refresh-dependencies

ランタイム／ネイティブエラー

症状：起動後のクラッシュ、ネイティブスタックトレース 診断：

# iOS: Check Xcode console and crash logs
# Open Xcode > Window > Devices and Simulators > View Device Logs

# Android: Check Logcat
adb logcat *:E | grep -E "(ReactNative|RN|React)"

Metro／バンドラーのエラー

症状：「Unable to load script」、バンドルの失敗 診断：

# Check Metro process
ps aux | grep metro

# Verify cache state
ls -la $TMPDIR/metro-*
ls -la node_modules/.cache/

依存関係／リンクエラー

症状：「Module not found」、「Native module cannot be null」 診断：

# Check installed dependencies
npm ls  # or: yarn list

# Verify native module linking (RN < 0.60)
npx react-native link

# Check auto-linking (RN >= 0.60)
npx react-native config

フェーズ 3：解決策

エラーの分類に基づいて修正を適用します。

最終手段（すべてをクリーンアップ）

ほかの方法がすべてうまくいかない場合は、完全なクリーンアップを実行します。

# 1. Stop all processes
# Kill Metro bundler (Ctrl+C or)
lsof -ti:8081 | xargs kill -9

# 2. Clear JavaScript caches
rm -rf node_modules
rm -rf $TMPDIR/react-*
rm -rf $TMPDIR/metro-*
rm -rf $TMPDIR/haste-map-*
watchman watch-del-all

# 3. Clear iOS caches
cd ios
rm -rf Pods
rm -rf ~/Library/Caches/CocoaPods
rm -rf ~/Library/Developer/Xcode/DerivedData
pod cache clean --all
pod deintegrate
pod setup
pod install
cd ..

# 4. Clear Android caches
cd android
./gradlew clean
rm -rf .gradle
rm -rf app/build
rm -rf ~/.gradle/caches
cd ..

# 5. Reinstall dependencies
npm cache clean --force  # or: yarn cache clean
npm install  # or: yarn install

# 6. Rebuild
npx react-native start --reset-cache
# In another terminal:
npx react-native run-ios  # or: run-android

Metro バンドラーの修正

# Reset Metro cache
npx react-native start --reset-cache

# Change Metro port if 8081 is occupied
npx react-native start --port 8082

# Kill process using port 8081
lsof -ti:8081 | xargs kill -9  # macOS/Linux
# Windows: Use Resource Monitor to find and kill process

# Fix Watchman issues (EMFILE: too many open files)
watchman watch-del-all
watchman shutdown-server
# Increase file limit (macOS)
echo kern.maxfiles=10485760 | sudo tee -a /etc/sysctl.conf
echo kern.maxfilesperproc=1048576 | sudo tee -a /etc/sysctl.conf
sudo sysctl -w kern.maxfiles=10485760
sudo sysctl -w kern.maxfilesperproc=1048576
ulimit -n 65536

iOS 固有の修正

# CocoaPods reinstall
cd ios
pod deintegrate
pod cache clean --all
rm Podfile.lock
pod install --repo-update
cd ..

# Xcode clean build
cd ios
xcodebuild clean -workspace YourApp.xcworkspace -scheme YourApp
cd ..

# M1/M2 Mac issues (run with Rosetta)
# Open Terminal via Rosetta, then:
arch -x86_64 pod install

# Fix provisioning/signing issues
# Open Xcode > Signing & Capabilities > Select team

# Reset iOS Simulator
xcrun simctl shutdown all
xcrun simctl erase all

Android 固有の修正

# Set Android SDK path
export ANDROID_HOME=~/Library/Android/sdk  # macOS
export ANDROID_HOME=~/Android/Sdk  # Linux
# Add to PATH
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/platform-tools

# Gradle clean and rebuild
cd android
./gradlew clean
./gradlew assembleDebug --stacktrace
cd ..

# Fix Gradle wrapper issues
cd android
rm -rf .gradle
./gradlew wrapper --gradle-version=8.3
cd ..

# Accept Android SDK licenses
yes | sdkmanager --licenses

# ADB issues
adb kill-server
adb start-server
adb devices

ネイティブモジュールのリンク修正

# For React Native >= 0.60 (auto-linking)
cd ios && pod install && cd ..
npx react-native run-ios

# For React Native < 0.60 (manual linking)
npx react-native link <package-name>

# Verify linking configuration
npx react-native config

# Rebuild after linking
cd android && ./gradlew clean && cd ..
cd ios && pod install && cd ..

Hermes エンジンの修正

# Verify Hermes is enabled (check android/app/build.gradle)
# hermesEnabled: true

# Clean Hermes bytecode cache
cd android && ./gradlew clean && cd ..

# iOS: Reinstall pods with Hermes
cd ios
pod deintegrate
pod install
cd ..

# Disable Hermes temporarily to test
# android/gradle.properties: hermesEnabled=false
# ios/Podfile: :hermes_enabled => false

依存関係の競合解決

# Check for duplicate packages
npm ls <package-name>

# Force resolution with npm
# Add to package.json:
# "overrides": { "problematic-package": "desired-version" }
npm install

# Force resolution with yarn
# Add to package.json:
# "resolutions": { "problematic-package": "desired-version" }
yarn install

# Deduplicate dependencies
npm dedupe  # or: yarn dedupe

フェーズ 4：検証と予防

修正を適用した後、解決策を検証します。

# 1. Run doctor again
npx react-native doctor

# 2. Start fresh Metro instance
npx react-native start --reset-cache

# 3. Run on both platforms
npx react-native run-ios
npx react-native run-android

# 4. Run tests
npm test  # or: yarn test

# 5. Check for TypeScript errors
npx tsc --noEmit

# 6. Run linter
npx eslint src/ --ext .js,.jsx,.ts,.tsx

予防策：

1. package.json で依存関係のバージョンを固定する
2. ネイティブモジュールには正確なバージョンを使用する
3. React Native のバージョンを更新しておく（メジャーバージョンの範囲内）
4. チーム全体で一貫した node_modules を維持する（ロックファイルを使用）
5. ネイティブ設定の変更を文書化する
6. CI/CD を使用して、ビルドの問題を早期に検出する
7. 本番環境でエラーバウンダリを有効にする
8. クラッシュレポート（Sentry、Crashlytics）を導入する

コマンド早見表

# Environment check
npx react-native doctor
npx react-native info

# Start with cache reset
npx react-native start --reset-cache

# Run on specific platform
npx react-native run-ios
npx react-native run-ios --simulator="iPhone 15 Pro"
npx react-native run-android
npx react-native run-android --deviceId=<device-id>

# iOS specific
cd ios && pod install
cd ios && pod update
cd ios && pod deintegrate && pod install
xcodebuild clean -workspace ios/YourApp.xcworkspace -scheme YourApp

# Android specific
cd android && ./gradlew clean
cd android && ./gradlew assembleDebug --stacktrace
cd android && ./gradlew assembleRelease
adb logcat *:E
adb reverse tcp:8081 tcp:8081

# Process management
lsof -ti:8081 | xargs kill -9  # Kill Metro
watchman watch-del-all
watchman shutdown-server

# Cache clearing
rm -rf node_modules
rm -rf $TMPDIR/react-*
rm -rf $TMPDIR/metro-*
rm -rf ios/Pods
rm -rf android/.gradle
rm -rf android/app/build

# Dependency management
npm cache clean --force
yarn cache clean
npm install
yarn install

# Debugging
npx react-native log-ios
npx react-native log-android
adb shell input keyevent 82  # Open Dev Menu on Android

# Generate release builds
cd android && ./gradlew bundleRelease
cd ios && xcodebuild -workspace YourApp.xcworkspace -scheme YourApp -configuration Release archive

プラットフォーム別のデバッグ

iOS デバッグチェックリスト

1. Xcode を開き、Issue Navigator（Cmd+5）を確認する
2. Debug エリアのコンソール出力（Cmd+Shift+C）を確認する
3. Signing & Capabilities の設定を確認する
4. Podfile と Podfile.lock でバージョンの不一致を確認する
5. ビルドフェーズとリンク済みフレームワークを確認する
6. Instruments を使用してメモリ／CPU のプロファイリングを行う
7. デバイスログを確認する：Window > Devices and Simulators

Android デバッグチェックリスト

1. Android Studio を開き、ビルド出力を確認する
2. Logcat でエラーを確認する：View > Tool Windows > Logcat
3. build.gradle の依存関係とバージョンを確認する
4. AndroidManifest.xml の権限を確認する
5. 難読化を使用している場合は、ProGuard ルールを確認する
6. パフォーマンスの問題には Android Profiler を使用する
7. デバイスの接続状態を adb devices で確認する

新しいアーキテクチャ（Fabric + TurboModules）

React Native の新しいアーキテクチャを使用している場合：

# Enable New Architecture (android/gradle.properties)
newArchEnabled=true

# Enable New Architecture (ios/Podfile)
ENV['RCT_NEW_ARCH_ENABLED'] = '1'

# Rebuild after enabling
cd ios && pod install
cd android && ./gradlew clean

# Common New Architecture issues:
# 1. Native modules not compatible - check for TurboModule support
# 2. Fabric renderer issues - verify component compatibility
# 3. Build failures - ensure correct versions of dependencies

エラー処理のベストプラクティス

// Implement Error Boundaries
import React, { Component, ErrorInfo, ReactNode } from 'react';

interface Props {
  children: ReactNode;
  fallback?: ReactNode;
}

interface State {
  hasError: boolean;
  error?: Error;
}

class ErrorBoundary extends Component<Props, State> {
  constructor(props: Props) {
    super(props);
    this.state = { hasError: false };
  }

  static getDerivedStateFromError(error: Error): State {
    return { hasError: true, error };
  }

  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
    // Log to error reporting service (Sentry, Crashlytics)
    console.error('Error caught by boundary:', error, errorInfo);
  }

  render() {
    if (this.state.hasError) {
      return this.props.fallback || <FallbackComponent error={this.state.error} />;
    }
    return this.props.children;
  }
}

// Async error handling
const fetchData = async () => {
  try {
    const response = await fetch(url);
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return await response.json();
  } catch (error) {
    console.error('Fetch error:', error);
    // Report to crash analytics
    throw error;
  }
};

デバッグワークフローの概要

1. 情報を収集する：npx react-native doctor を実行し、エラーメッセージを収集して、プラットフォームを特定する
2. エラーを分類する：JavaScript、ビルド、ランタイム、Metro、または依存関係の問題に分類する
3. 的を絞った修正を適用する：分類に基づいて、プラットフォーム固有のコマンドを使用する
4. 修正を検証する：両方のプラットフォームでテストを実施し、テストを実行して、デグレードがないか確認する
5. 文書化する：問題の原因と解決方法を記録する

覚えておいてください。React Native の問題のほとんどは、キャッシュをクリアして再ビルドすることで解決できます。判断に迷った場合は、「最終手段」のクリーンアップを実行して再ビルドしてください。