Rorkアプリのビルドエラーを体系的に切り分けて直す

Rorkアプリを開発していると、ビルドプロセスでエラーが発生することがあります。これらのエラーは複雑に見えますが、体系的に対処すれば必ず解決できます。ここではRorkアプリ開発で最も一般的なビルドエラーの原因と解決方法を段階的に解説します。

ビルドエラーの3層構造を理解する

Rorkアプリのビルドエラーは、大きく3つの層に分かれます。

依存関係層（npm/yarn）: JavaScriptパッケージの解決エラー
ネイティブ層（iOS/Android）: プラットフォーム固有のネイティブビルド失敗
型チェック層（TypeScript）: 型定義エラー

各層のエラーを理解することで、デバッグが格段に効率化します。

よくあるビルドエラーと解決策

1. NPM依存関係エラー「npm ERR! code ERESOLVE」

このエラーはnpmがパッケージ間の依存関係を解決できない時に発生します。

原因：

パッケージのバージョン不一致
ピア依存性（peerDependencies）の競合
キャッシュの破損

解決方法：

# Step 1: node_modulesとpackage-lock.jsonをクリア
rm -rf node_modules package-lock.json
 
# Step 2: キャッシュをクリア（重要）
npm cache clean --force
 
# Step 3: package.jsonから不要な依存関係を削除
# 開発途中に追加した不要なパッケージがないか確認する
 
# Step 4: 依存関係を再インストール（--legacy-peer-deps で強制インストール）
npm install --legacy-peer-deps
 
# Step 5: it not a issue if build still fails
# package.jsonでconflictのあるバージョンを手動調整

よくある競合パターン：

// package.json - 推奨バージョン範囲
{
  "dependencies": {
    "react": "^18.2.0",
    "react-native": "0.73.0",
    "expo": "^50.0.0"
  },
  "devDependencies": {
    "typescript": "^5.3.0"
  }
}

2. CocoaPodsエラー「pod install」失敗（iOS）

Rorkで生成されるiOSアプリはCocoaPodsで依存関係を管理します。

原因：

ローカルCocoaPodsリポジトリの破損
iOSデプロイメント対象バージョンの不一致
M1/M2 Macのアーキテクチャ互換性問題

解決方法：

# Step 1: ios/フォルダに移動
cd ios
 
# Step 2: CocoaPodsキャッシュをリセット
rm -rf Pods Podfile.lock
 
# Step 3: CocoaPodsリポジトリをリセット
pod repo update
 
# Step 4: pod installを実行
pod install
 
# Step 5: M1/M2 Macの場合は architecture を指定
# Podfile の最後に以下を追加:
# post_install do |installer|
#   installer.pods_project.targets.each do |target|
#     flutter_additional_ios_build_settings(target)
#     target.build_configurations.each do |config|
#       config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= [
#         '$(inherited)',
#         'COCOAPODS=1',
#       ]
#     end
#   end
# end

3. Gradleエラー「Gradle sync failed」（Android）

AndroidプロジェクトはGradleでビルドされます。

原因：

Android SDKのバージョン不一致
targetSdkVersionが古い
Java/Kotlin のバージョン不一致

解決方法：

# Step 1: android フォルダに移動
cd android
 
# Step 2: Gradle キャッシュをクリア
./gradlew clean
 
# Step 3: build.gradle を確認し targetSdkVersion を更新
# android/build.gradle の確認:
# ext {
#   buildToolsVersion = "35.0.0"
#   targetSdkVersion = 35
#   compileSdkVersion = 35
# }
 
# Step 4: Gradle デーモンをリセット
./gradlew --stop
 
# Step 5: 再度ビルド
./gradlew assembleDebug

4. TypeScript型エラー「Type 'X' is not assignable to type 'Y'」

開発中のTypeScriptコンパイルエラーです。

原因：

型定義ファイル(@types)の不足
インポートパスの誤り
React/React Nativeの型バージョン不一致

解決方法：

// ❌ 悪い例：型エラー
const handlePress = (event) => {
  console.log(event);
};
 
// ✅ 良い例：型を明示
import { GestureResponderEvent } from 'react-native';
 
const handlePress = (event: GestureResponderEvent): void => {
  console.log(event);
};
 
// 必要な@typesパッケージをインストール
// npm install --save-dev @types/react-native

tsconfig.json の確認：

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020"],
    "jsx": "react-native",
    "strict": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

5. バンドルエラー「Metro bundler error」

Rorkの開発サーバーがMetroバンドラーを使用していて、ここでエラーが発生することがあります。

原因：

キャッシュの破損
循環参照（circular dependencies）
存在しないモジュールの import

解決方法：

# Step 1: Metroキャッシュをクリア
rm -rf /tmp/metro-*
# または
npm start -- --reset-cache
 
# Step 2: node_modules再インストール
rm -rf node_modules
npm install
 
# Step 3: ウォッチャーをリセット
# macOSでファイルシステムキャッシュの問題がある場合
npx react-native start --reset-cache
 
# Step 4: 循環参照がないか確認
# index.js（またはメインエントリーファイル）を確認

システムレベルのビルドリセット手順

上記の個別対処でも解決しない場合は、システムレベルでリセットします。

#!/bin/bash
# build-reset.sh - 完全ビルドリセット
 
echo "🧹 Cleaning build cache..."
 
# npm/yarn キャッシュ
rm -rf node_modules package-lock.json yarn.lock
npm cache clean --force
 
# iOS ビルド成果物
rm -rf ios/Pods ios/Podfile.lock
rm -rf ~/Library/Developer/Xcode/DerivedData/*
 
# Android ビルド成果物
rm -rf android/.gradle android/build android/app/build
 
# Metro バンドラー キャッシュ
rm -rf /tmp/metro-*
rm -rf ~/.rn-cli.config.js
 
# 再インストール
npm install --legacy-peer-deps
npm start -- --reset-cache
 
echo "✅ Build cache reset complete"

ビルドエラーのデバッグテクニック

ダーティビルド vs クリーンビルド

ダーティビルドでエラーが発生する場合、クリーンビルドで検証します：

# クリーンビルド（推奨）
npm run clean    # ローカル定義の clean スクリプト
npm install
npm start
 
# または個別に
rm -rf node_modules package-lock.json
npm install

エラーメッセージの読み方

ビルドエラーメッセージは下から上へ読みます：

Error at /path/to/file.js:10:5
  Expected token, found 'something'
  at Parser.raise (parser.js:1000:20)

実際のエラー箇所は /path/to/file.js の10行目5列です。

VSCode統合で型エラーを早期発見

// .vscode/settings.json
{
  "typescript.tsdk": "node_modules/typescript/lib",
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  }
}

よくあるビルドエラーQ&A

Q1: 「error: ReferenceError: DEV is not defined」が出ます

A: Rorkプロジェクトの metro.config.js に以下を追加：

module.exports = {
  transformer: {
    getTransformOptions: async () => ({
      transform: {
        experimentalImportSupport: false,
        inlineRequires: false,
      },
    }),
  },
};

Q2: M1 Macでのビルド失敗「error: No platform specified」

A: Podfile で platform を明示：

platform :ios, '13.0'
 
# または Xcode で Architectures を arm64 に設定

Q3: ビルドは成功するが、実行時に「Cannot find module」エラーが出ます

A: アプリケーションレベルの require/import エラーです。パスを確認：

// ❌ 間違い
import { Button } from './button'  // ファイルが存在しない
 
// ✅ 正しい
import { Button } from './components/button'

全体を振り返って

Rorkアプリのビルドエラーの多くは、依存関係のクリーンアップと型チェックで解決します。重要な対処順序は：

キャッシュをクリア（npm, CocoaPods, Gradle, Metro）
依存関係を再インストール（--legacy-peer-deps オプション検討）
型チェックを実行（TypeScript strict mode）
プラットフォーム固有の設定を確認（iOS/Android）

ビルドエラーに直面した時は、焦らずエラーメッセージを最後まで読み、上記の層構造に従ってシステマティックに対処することが成功の鍵です。

Rorkアプリのビルドエラーを体系的に切り分けて直す

ビルドエラーの3層構造を理解する

よくあるビルドエラーと解決策

1. NPM依存関係エラー「npm ERR! code ERESOLVE」

2. CocoaPodsエラー「pod install」失敗（iOS）

3. Gradleエラー「Gradle sync failed」（Android）

4. TypeScript型エラー「Type 'X' is not assignable to type 'Y'」

5. バンドルエラー「Metro bundler error」

システムレベルのビルドリセット手順

ビルドエラーのデバッグテクニック

ダーティビルド vs クリーンビルド

エラーメッセージの読み方

VSCode統合で型エラーを早期発見

よくあるビルドエラーQ&A

全体を振り返って

お読みいただきありがとうございます

関連記事