UnityのUndefined symbolエラー — iOSビルドの直し方

UnityのUndefined symbolエラーに、iOS実機ビルドで当たりました。9件出て止まり、通知機能はひとつも実装していません。

原因は UserNotifications.framework がリンクされていなかったことでした。Xcodeで2つのフレームワークを追加したら通りました。以下は実際に踏んだ手順です。

この記事について — 筆者が実際に遭遇し、解決した内容です（記事種別: 実測）。掲載しているスクリーンショットは実機の画面です。原因の解説部分には、Unity Discussions の同種の報告を参照しています。

<!– 要素材: Unity のバージョン、Xcode のバージョン、Mobile Notifications パッケージの有無。 実測記事なので環境を明記したほうが読者の再現性が上がる。分かれば追記する –>

出たエラー

Unity 側のビルドは成功し、Xcode で実機ビルドに進んだところで止まりました。

Undefined symbol: _OBJC_CLASS_$_UNCalendarNotificationTrigger
Undefined symbol: _OBJC_CLASS_$_UNLocationNotificationTrigger
Undefined symbol: _OBJC_CLASS_$_UNMutableNotificationContent
Undefined symbol: _OBJC_CLASS_$_UNNotificationRequest
Undefined symbol: _OBJC_CLASS_$_UNNotificationSound
Undefined symbol: _OBJC_CLASS_$_UNPushNotificationTrigger
Undefined symbol: _OBJC_CLASS_$_UNTextInputNotificationResponse
Undefined symbol: _OBJC_CLASS_$_UNTimeIntervalNotificationTrigger
Undefined symbol: _OBJC_CLASS_$_UNUserNotificationCenter

9件すべてが 0 で始まっています。これは UserNotifications フレームワークのクラスに付く接頭辞です。エラーの中身がバラバラに見えても、出どころは1つでした。

なぜ通知を使っていないのに出るのか

Undefined symbol は、コードがそのシンボルを参照しているのに、リンク時に実体が見つからないときに出ます。今回で言えば、ビルドされたコードが UNUserNotificationCenter などを呼んでいる。ところが、その実装を持つ UserNotifications.framework がリンク対象に入っていませんでした。

腑に落ちなかったのは、自分では通知を一切実装していない点でした。

調べると、Unity Discussions に同じ症状の報告がありました。iOSビルドで UserNotifications フレームワークが不足して失敗するのは、繰り返し起きている問題のようです。

自分で通知コードを書いていなくても、依存しているパッケージが通知のシンボルを参照していることがあります。Unity の Mobile Notifications パッケージのほか、広告・解析・各種SDKが内部で使う場合です。UnityFramework にはその参照が残るのに、Xcodeプロジェクト側でフレームワークが自動リンクされない。ここがずれていました。

エラーの原因は自分のコードではなく、依存関係のほうにありました。

直した手順

Xcode で UnityFramework ターゲットにフレームワークを2つ追加します。

1. Xcode でプロジェクトを開く
2. 左のプロジェクトファイルを選択 → TARGETS から 0 を選ぶ
3. General タブ → Frameworks and Libraries セクション
4. ＋ボタンをクリック
5. UserNotifications.framework を追加
6. UserNotificationsUI.framework を追加

ターゲットの選択を間違えないでください。 Unity-iPhone ではなく 1 です。シンボルを参照しているのは UnityFramework 側なので、Unity-iPhone に追加してもエラーは消えません。

追加後に再ビルドしたところ、実機ビルドが成功しました。

直らないときに見るところ

同じエラーが残る場合、次を順に確認してください。

確認する場所	見るもの
ターゲット	UnityFramework に追加したか（Unity-iPhone ではない）
Build Phases	Link Binary With Libraries に2つとも載っているか
Embed 設定	Do Not Embed で問題ありません。OS標準のフレームワークです
Clean Build	フレームワーク追加後に Product > Clean Build Folder
残りのシンボル	UN 以外の接頭辞なら別のフレームワーク不足です

最後の行が実務的に効きます。接頭辞を見れば、どのフレームワークが足りないか当たりが付きます。

接頭辞	フレームワーク
UN	UserNotifications
CB	CoreBluetooth
AV	AVFoundation
CM	CoreMotion / CoreMedia
SK	StoreKit / SpriteKit

Unity側から毎回入れる方法

Unityから書き出すたびにXcodeで手作業を繰り返すのは現実的ではありません。恒久対応にするなら、ビルド後処理でフレームワークを追加する方法があります。

Assets/Editor/ に PostProcessBuild を使ったスクリプトを置き、PBXProject でフレームワークを追加する形です。CIやクラウドビルドを使う場合は、この対応が実質的に必須になります。

<!– 要素材: 実際に PostProcessBuild スクリプトを書いて動かしたなら、そのコードを載せる。 未検証の内容をコードとして載せない –>

まとめ

• Undefined symbol は、参照はあるのに実体がリンクされていない状態を指します
• 9件のエラーはすべて UN 接頭辞で、出どころは UserNotifications ひとつでした
• 通知を実装していなくても、依存パッケージが参照していれば起きます
• 追加先は Unity-iPhone ではなく 1
• 接頭辞から不足フレームワークを逆引きできます

よくある質問

Unity-iPhone ターゲットに追加してはいけませんか

そちらに追加してもエラーは消えません。シンボルを参照しているのは UnityFramework 側だからです。両方に追加しても害はありませんが、必要なのは UnityFramework のほうです。

UserNotificationsUI.framework も必要ですか

筆者は2つとも追加して解決しました。UserNotificationsUI は通知のカスタムUIに使うもので、片方だけで通る場合もあります。切り分けが目的でなければ、2つ入れておくのが早いです。

Embed は Do Not Embed のままでいいですか

問題ありません。OSに標準で入っているフレームワークなので、アプリに同梱する必要はありません。

通知を使わないのに、この参照を消せませんか

参照元のパッケージを外せば消えます。ただし広告や解析のSDKが依存していることが多く、外すと別の機能が失われます。フレームワークを1つ足すほうが影響が小さい判断になります。

別の Undefined symbol が出ました

シンボルの接頭辞を確認してください。UN 以外なら別のフレームワークです。上の対応表から当たりを付けて、同じ手順で UnityFramework に追加します。