最近、React Native(Expo)で作っているアプリを、いよいよMac miniのXcodeから実機(iPhone)でデバッグしようとしたのですが、これがもう一筋縄ではいきませんでした。
「ケーブルで繋いでビルドボタンを押すだけでしょ?」と軽く考えていたのですが、接続のペアリングで弾かれ、署名で弾かれ、規約で弾かれ、最終的にはmacOSのメジャーアップデートまで走るハメに……。一つ解決するとまた次のエラーが顔を出す、まさにエラーのモグラ叩き状態でした。
ただ、振り返ってみるとこれらは実機デバッグでよくハマる定番ポイントばかり。同じ轍を踏む人のために、つまずいた箇所と解決法を順を追ってまとめておきます。脱・実機デバッグ初心者の内容になりますので、これから実機ビルドに挑む方はぜひ目を通しておくことをおすすめします。
実機デバッグ、なぜか繋がらない!
シミュレータでは普通に動くのに、いざ実機でとなると途端に動かなくなる。iOS開発あるあるですね。特にReact Native + Expoの構成は、JavaScript・ネイティブ・ビルドツール・署名と、関係する層が多いぶん、トラブルの種も多めです。
今回遭遇したエラーを発生順に潰していきます。
① デバイスのペアリングで認証失敗
最初の壁がこれ。Devices and SimulatorsでiPhoneを繋いだものの、こんなエラーが出ました。
Failed to authenticate the user to complete the pairing.
Disconnect and reconnect the USB cable, then follow instructions on the device原因はシンプルで、ペアリング時にiPhone側に出る「信頼しますか?」のダイアログに素早く反応できていないことがほとんどです。
対処法は以下の通り。
- iPhoneのロックを解除し、ホーム画面の状態にしてから再接続する
- それでもダメなら信頼設定をリセット(
設定→一般→転送またはiPhoneをリセット→リセット→位置情報とプライバシーをリセット) - 純正(MFi認証)ケーブルを使い、ハブを経由せず直挿しする
意外とケーブルとダイアログのタイミングだけの問題だったりするので、まずはここを疑いましょう。
② 開発チーム(Team)が設定されていない
ペアリングが通ると、今度はビルドでこのエラー。
Signing for "MyPictureDefender" requires a development team実機にアプリを入れるには、Apple IDに紐づいた「開発チーム」が必要です。Signing & CapabilitiesのTeamが「Add Account…」のままだと、まだApple IDすら登録されていない状態。
ここで普段使っているApple IDを追加すればOK。有料のApple Developer Programは不要で、無料のPersonal Teamで実機テストはできます。ただし無料枠には以下の制限がある点だけ覚えておきましょう。
- 証明書の有効期限は7日間(切れたら再ビルド)
- 同時にインストールできるアプリは3つまで
③ PLA(ライセンス規約)に未同意
Apple IDを追加したのに、今度はこんなエラーが。
Unable to process request - PLA Update available
You currently don't have access to this membership resource.これはApple側の利用規約(Program License Agreement)が更新されていて、未同意のままになっているパターン。Xcode上では同意できないので、ブラウザで developer.apple.com/account にログインして規約に同意し、Xcodeに戻って「Try Again」を押すだけ。
Appleが定期的に規約を更新するので、これは誰でも遭遇しうる定番です。
④ CocoaPodsの同期エラー
署名まわりが片付いたと思ったら、お次はこれ。
The sandbox is not in sync with the Podfile.lock. Run 'pod install'ここで「そもそもPodって何?」となる方も多いと思います。CocoaPodsはiOS開発のライブラリ依存関係管理ツールで、npmやpipのiOS版のようなもの。React Nativeアプリは内部でネイティブの部品(カメラ、通知、Expoモジュールなど)を組み合わせて動いていて、それらをXcodeプロジェクトに橋渡しするのがCocoaPodsの役割です。
package.json (npm) → node_modules/ にJSライブラリ
ios/Podfile (Pod) → ios/Pods/ にネイティブライブラリ対処はiosフォルダでpod installを実行。なお、構成が大きく変わったときは中途半端に直すより、いっそ作り直したほうが確実です。
bash
cd ios
rm -rf Pods Podfile.lock
rm -rf ~/Library/Developer/Xcode/DerivedData/MyPictureDefender-*
pod cache clean --all
pod install⑤ 真の黒幕、Swiftバージョンの不整合
ここが今回の最大の山場でした。ビルドすると大量のmodule map not foundエラーが噴出。一見すると意味不明ですが、Report Navigatorでログを一番下までスクロールして真犯人を発見しました。
xcodebuild: error: Could not resolve package dependencies:
package 'apple' is using Swift tools version 6.2.0 but the installed version is 6.0.0つまり、ライブラリ側がSwift 6.2を要求しているのに、手元のXcode 16.2に入っているSwiftは6.0しかない、というバージョン不一致。Swift 6.2が同梱されるのはより新しいXcodeで、それには新しいmacOSが必要……ということで、
- macOSをSequoia(15以上)にアップデート
- その後Xcodeを最新版にアップデート
という大がかりな対応に。sw_versでOSバージョン、xcodebuild -versionでXcodeのバージョンを確認しておくと状況を把握しやすいです。
ちなみにこの過程で、ターミナルがxcodebuildを見つけられないトラブルもありました。
xcode-select: error: tool 'xcodebuild' requires Xcode, but active developer
directory '/Library/Developer/CommandLineTools' is a command line tools instanceこれはコマンドラインの参照先がCommand Line Toolsになっているだけなので、フルのXcodeを指し直せば解決します。
bash
sudo xcode-select -switch /Applications/Xcode.app/Contents/Developer⑥ Sentryの自動アップロードで失敗
アップデートを経てmodule mapエラーは消え、ビルドは100秒以上進むように。あと一歩!というところでまた別のエラー。
sentry-cli - An organization ID or slug is required (provide with --org)これはエラー監視SDKのSentryが、ビルド時にソースマップを自動アップロードしようとして設定不足で失敗しているもの。実機デバッグの段階ではアップロードは不要なので、無効化してしまえばOKです。
ios/.xcode.env.localに一行追記します。
bash
echo 'export SENTRY_DISABLE_AUTO_UPLOAD=true' >> .xcode.env.local⑦ Metroサーバーが起動していない
ついにビルド成功!アプリが実機にインストールされて起動……と思いきや、画面にこんなメッセージが。
No script URL provided. Make sure the packager is running or you have embedded a JS bundleこれはエラーではなく、JavaScriptを配信するMetroサーバーが起動していないだけ。ネイティブ部分(アプリの殻)は起動したものの、中身のJSコードを読み込めていない状態です。
ここで注意なのが、Expoプロジェクトなのでreact-native startではなくexpo startを使うこと。
npx expo startさらに、Xcodeから入れたのはExpo Goではなく独自のDevelopment Buildなので、Metro起動後にsキーを押してDevelopment buildモードに切り替える必要がありました。これで無事、実機でアプリが正常起動!長い戦いが終わりました。
エラーログの追い方のコツ
今回いちばん効いたのは、エラーログを最後まで諦めずに追ったことです。具体的には以下の流れ。
- Report Navigator(時計アイコン)で最新のビルドログを開く
- 右上の「Errors Only」で警告を除外し、エラーだけに絞る
- 表示されたログを一番下までスクロールして、
error:で始まる本当の原因を探す
module map not foundのような大量のエラーは、たいてい「結果」であって「原因」ではありません。本当の原因(今回ならSwiftバージョン)はログの末尾にひっそり書かれていることが多いので、表面的なエラーの数に惑わされないことが大切です。
まとめ
React Native + Expoの実機デバッグは、接続・署名・規約・依存関係・ツールチェーン・開発サーバーと、関門が非常に多いです。しかし裏を返せば、ハマるポイントはだいたい決まっているということ。
- ペアリング失敗 → ダイアログのタイミングとケーブルを疑う
- 署名エラー → TeamとPLA同意を確認
- module mapの大量エラー → ログの末尾で真の原因(Swiftバージョン等)を探す
- アプリは起動するが白画面 → Metroサーバーとビルドモードを確認
一度通してしまえば、次からは格段にスムーズになります。同じところでハマっている方の助けになれば幸いです……自戒も込めて。
