Rork でアプリがビルドできないとき、最初に切り分ける 8

個人開発でアプリを作っていると、ビルドが通らない夜に必ず当たります。エラーの文面を検索して、出てきた手順を片っ端から試して、気づけば別の場所まで壊していました。最初のうち、私はこの回り道をたびたびしていました。

いま振り返ると、原因は「手順を知らなかったこと」より、どの層で起きているのかを見ずに直そうとしたことにありました。依存パッケージの問題なのか、開発環境の問題なのか、Rork 側の生成の問題なのか。層がわかれば、試す手順はほとんど一つに絞れます。

この FAQ は 8 つの症状を、その層ごとに並べ直したものです。上から順に読むより、いま出ている症状の Q だけ開いていただければ十分です。

まず切り分けの早見表です。

症状	疑う層	見る Q
ビルド失敗・peer dependency の文言	パッケージ	Q1
Unable to resolve module	パッケージ／キャッシュ	Q2
シミュレーターが起動しない	開発環境（Xcode）	Q3
エミュレーターが白い画面のまま	開発環境（Android）	Q4
生成が途中で止まる	Rork 側／通信	Q5
画像やアイコンが出ない	アセット／パス	Q6
変更が反映されない	Metro／接続	Q7
エラーに Fix Now が出ている	コード（機械的な誤り）	Q8

Q1: 「ビルドに失敗しました」と出ます。依存関係の競合とは何ですか？

A: もっとも多い原因は、複数のパッケージが互いに合わないバージョンを要求している状態です。たとえばパッケージ A はライブラリ X の 1.x を、パッケージ B は 2.x を必要としている、といった具合です。

エラーログに conflicting peer dependency や ERESOLVE と出ていれば、ほぼこれです。

# 依存を作り直す（node_modules と lock を捨てて入れ直す）
rm -rf node_modules package-lock.json
npm cache clean --force
npm install

それでも npm install が止まる場合は、--legacy-peer-deps を付けると peer 依存の厳密なチェックを緩めて進められます。

npm install --legacy-peer-deps

:::warning --legacy-peer-deps は競合を「解決」するのではなく「見ないことにする」オプションです。通ったあとでアプリが起動するか必ず確かめ、動かなければ、ログに名前が出ているパッケージのバージョンを揃える方向へ戻ります。 :::

Expo SDK に紐づくパッケージ（expo-* や react-native-* の一部）は、npm install ではなく次のコマンドで SDK 版に合う版へ揃えるのが安全です。

npx expo install --fix

Q2: Expo モジュールが見つからないというエラーが出ます

A: Unable to resolve module や Cannot find module は、依存が入っていないか、Metro のキャッシュが古いかのどちらかであることがほとんどです。

# 1. lock ファイルどおりに入れ直す
npm ci
 
# 2. Metro のキャッシュを捨てて起動
npx expo start --clear

以前の記事や古い解説では npm install -g expo-cli を勧めているものがありますが、グローバルの expo-cli は現在は使わず、プロジェクト内の npx expo ... を使うのが基本です。グローバルに古い版が残っていると、プロジェクトの SDK 版とずれて余計な混乱を呼びます。

npx expo --version   # プロジェクトに入っている Expo の版が出れば OK

手触りとして覚えておきたいのは、npm ci は「lock に書かれた状態を再現する」コマンドで、npm install は「いまの状態から良さそうに整える」コマンドだということです。再現したいときは ci です。

Q3: iOS シミュレーターが起動しません

A: 層は開発環境です。コードはほぼ関係しません。順に疑う場所は 3 つです。

Xcode とコマンドラインツール（macOS のみ）

xcode-select --install
xcode-select -p   # パスが表示されれば有効

シミュレーターの実体

xcrun simctl list devices available
xcrun simctl boot "iPhone 16 Pro"   # 一覧に出た名前を指定

ポート 8081 の取り合い

lsof -i :8081          # 占有しているプロセスを確認
npx expo start -p 8082 # 別ポートで起動

:::tip どうしてもシミュレーターが言うことを聞かない夜は、実機の Expo Go で確認する手があります。シミュレーター固有の不具合を丸ごと迂回できるので、アプリ側の問題かどうかを先に確かめられます。 :::

Q4: Android エミュレーターが白い画面のまま動きません

A: 白い画面は「何も描画できていない」状態で、原因はビルド未完了、JDK、エミュレーターの余力、接続の 4 か所に分かれます。

まず Metro のキャッシュを捨てて再起動します。

npx expo start --clear

ターミナルに bundling の進行が出ているのを確かめてから、エミュレーターを r でリロードします。進行が出ていない場合は、エミュレーターではなくターミナル側に原因があります。

JDK を確認します。

java -version

Expo の推奨する JDK は SDK 版ごとに変わります。ここでは数字を固定せず、お使いの Expo SDK の公式ドキュメントで JDK の要件を確かめていただくのが確実です。

エミュレーターのメモリが少ない場合は、Android Studio の Device Manager から該当デバイスを編集し、RAM を増やします。それでも改善しなければ、一度 Cold Boot（保存済み状態を使わない起動）を試します。

:::warning 白い画面のとき、画面そのものを見つめても答えは出ません。答えはたいていターミナルの赤い行に書いてあります。 :::

Q5: プロンプトからアプリが生成されません。生成が止まってしまいます

A: 層は Rork 側と通信です。コードを触る前にできることが 3 つあります。

1 つ目は、プロンプトを小さくすること。機能を一度にすべて書き込むと、生成が長引いて止まったように見えます。基本機能だけで作らせて、あとから足すほうが結果は安定します。

// 詰め込みすぎ
「チャットアプリ。リアルタイム通知、プロフィール画像、検索、
グループ、ボイスメッセージ、ビデオ通話、ブロック、既読…」

// 小さく始める
「チャットアプリ。ユーザーはメッセージを送受信できる。
UI はシンプルで十分。」

2 つ目は、通信の確認です。Wi-Fi が不安定なときは生成が途中で止まります。切り替えてから、もう一度試します。

3 つ目は、ブラウザ側の余裕です。タブを多く開いていると重くなります。不要なタブを閉じ、改善しなければ別のブラウザで試します。

Q6: 画像やアイコンが表示されません

A: 多くはパスかパッケージ名の取り違えです。

画像は相対パスの階層を 1 つ間違えるだけで消えます。

// ファイルの位置に対してパスを数え直す
<Image source={require('../../assets/images/my-image.png')} />

アイコンは、@expo/vector-icons を使うのが標準です。パッケージ名の取り違えがよくあります。

npx expo install @expo/vector-icons

ファイル名にスペースや日本語が入っていると、環境によって解決に失敗します。英数字とハイフンかアンダースコアだけにしておくと安全です。表示が古いままなら、npx expo start -c でキャッシュを捨てます。

Q7: ホットリロードが効きません。変更が反映されません

A: 現在の Expo では Fast Refresh が既定で有効なので、--hot のようなフラグは不要です。効かないときは、次の順で確認します。

保存されているか。エディタのタブに未保存の印が付いていないか。
構文エラーがないか。赤いエラー画面が出ていれば、直すまで反映されません。
接続が切れていないか。端末と開発 PC が同じネットワークにいるかを確認します。
開発者メニューから Reload。iOS シミュレーターは Cmd + D、Android エミュレーターは Cmd + M（Windows は Ctrl + M）です。

それでも直らなければ、Metro を止めて npx expo start --clear で起動し直します。

:::tip 反映が 1〜2 秒遅れるのは異常ではありません。開発中の React が、確認のために同じ描画を 2 回行うことがあるためです（本番ビルドでは起きません）。 :::

Q8: 「Fix Now」ボタンは使っても大丈夫ですか？

A: 使いどころを選べば、とても頼れます。Rork はビルドや実行でエラーが起きると、エラー内容のすぐ下に「Fix Now」を表示することがあります。エラーメッセージと前後のコードを AI に渡し、修正案を適用する機能です。

得意なのは、原因がメッセージに書いてあるエラーです。 閉じ忘れた括弧、import の書き忘れ、存在しない関数名、型の不一致など。この種類は、一度押すだけで解決することが多いです。

苦手なのは、コードの外に原因があるエラーです。 依存関係の競合（Q1）、シミュレーターやエミュレーターの不調（Q3・Q4）、生成のフリーズ（Q5）。これらは「コードを直す」問題ではないので、見当違いの修正が当たってしまうことがあります。

私は次の順で使っています。

まず、メッセージを一度自分で読みます
構文や import 系のエラーなら、Fix Now を押します
適用された差分に、必ず目を通します
同じ Fix Now を 2 回続けても直らなければ、止めて Q1〜Q7 の層の切り分けに戻ります

中身を見ずに押し続けないこと——この一線だけは守るようにしています。AI が別の場所まで書き換えて、状況がかえって複雑になることがあるからです。

次の一歩

ビルドエラーに出会ったら、まずエラーメッセージを最後まで読み、「パッケージ・開発環境・Rork 側・コード」のどの層かを一つ決めます。そのうえで、その層の Q だけを試します。

いま振り返ると、焦っているときほど最初の赤い行を飛ばしていたのだと思います。今夜ビルドが通らずに困っている方は、ターミナルの最初の赤い行をコピーして、早見表の症状と見比べてみていただければと思います。

Rork でアプリがビルドできないとき、最初に切り分ける 8 つの症状