Unityで「Assembly definition references missing」が出る原因と解決方法【asmdef参照エラー対策】

Unityで突然「Assembly definition references missing」が出ると、かなり焦りますよね。

特にこんな状況、経験ありませんか？

• Package Managerで不要そうなパッケージを削除した
• アセットを導入した直後に大量エラーが出た
• asmdefを整理していたらコンパイルが通らなくなった
• 「Missing」を消していいのか分からない

私も最初の頃、「なんかUnity壊れた…？」って本気で思いました🙂

でも実際は、プロジェクト全体が壊れているケースよりも、asmdef（Assembly Definition）の参照関係がズレているだけのことがかなり多いです。

ただ、このエラーがややこしいのは、原因が1つではないところなんですよね。

• パッケージ削除による依存切れ
• Editor専用コードの参照ミス
• asmdef名変更によるリンク切れ
• Define Constraintsによる除外

……など、見た目は同じエラーでも中身が違います。

その状態で「とりあえずMissingを削除」で進めると、あとから別の機能まで壊れることもあります。

逆に、確認ポイントさえ分かっていれば、このエラーはかなり高い確率で落ち着いて直せます。

今回は、「Assembly definition references missing」が出た時に最初に見るべき場所から、asmdefの依存構造、Editor/Runtime分離、GUID設定まで、実際によくある失敗パターンと一緒に整理していきます。

---

Unity「Assembly definition references missing」の原因は参照切れ

このエラーが出た時、まず押さえておきたいのは、「asmdefが参照している別アセンブリを見つけられない状態」だということです。

つまり、Unityが「このコードをコンパイルしたいけど、必要な部品が足りないよ」と言っているイメージですね。

なので、最初にやるべきなのは、スクリプトを書き換えることではありません。

「どの参照がMissingになっているか」を確認することが最優先です。

このエラーは「参照先アセンブリが見つからない」状態

asmdef（Assembly Definition）は、コードをアセンブリ単位で分割する設定ファイルです。

そして、asmdef同士は「Assembly Definition References」で依存関係を持っています。

たとえばこんな構造です。

• Gameplay.asmdef → Inventory.asmdef を参照
• UI.asmdef → Gameplay.asmdef を参照
• EditorTools.asmdef → UnityEditor系を参照

この時、参照先のasmdefが削除されたり、コンパイル対象外になったりすると、「references missing」が発生します。

ここで勘違いしやすいのですが、Missing = ファイルが完全に消えたとは限りません。

たとえば次のケースでも発生します。

• Package削除で依存アセンブリが消えた
• Platforms設定でEditor専用になった
• Define Constraintsでコンパイル除外された
• asmdef名変更で参照先を見失った

なので、「Missingだからファイル探そう！」だけでは空振りすることも多いんです。

まず最初に確認するべき場所

最短で原因を見つけたいなら、次の順番がおすすめです。

1. Consoleでエラーを確認
2. エラー内のasmdefを特定
3. Inspectorの「Assembly Definition References」を確認

特に重要なのが、Inspectorのこの部分です。

• Assembly Definition References
• Platforms
• Define Constraints

ここを見ると、「どの参照がMissingなのか」がかなり高い確率で分かります。

逆に、ここを見ずにLibrary削除やReimport Allを始めると、時間だけ溶けることがあります。Unityあるあるですね……。

最短で直したい人向けの結論

急ぎで復旧したい場合は、まずこの流れで確認してみてください。

状況	まず疑う場所
Package削除後に発生	依存Package不足
Editor追加後に発生	Runtime→Editor参照
asmdef名変更後に発生	GUID未使用
特定Platformのみ発生	Platforms / Define Constraints

特に多いのは、「不要だと思って消したPackageが、別asmdefから参照されていた」パターンです。

---

Unity asmdefエラーが出る4つの原因

「Assembly definition references missing」は、見た目は同じでも原因がかなり分かれます。

ここを切り分けずに修正を始めると、直ったように見えて別の場所が壊れることもあります。

まずは、Unityで特に多い4パターンを整理しておきましょう。

Package削除で依存アセンブリが消えた

一番よくあるのがこれです。

たとえば、Package Managerで不要そうなパッケージを削除した時。

実は別のasmdefが、そのPackage内アセンブリを参照していた……というケースがかなりあります。

よくある例はこちらです。

• Input System
• Addressables
• Odin Inspector
• Easy Save
• TextMeshPro系拡張

特にアセットストア製ツールは、内部でasmdef依存を持っていることが多いです。

「この機能使ってないから消してOKでしょ」と思って削除すると、別機能まで巻き込まれることがあります。

最近Package整理した記憶があるなら、まずここを疑うのがおすすめです。

Editor拡張系アセットを使っている場合は、依存関係が複雑になりやすいので注意してください。

Odin Inspector のような高機能アセットは便利ですが、asmdef構成も本格的なので、Package整理時は依存確認をしておくと安全です。

RuntimeからEditorを参照している

Unityには、RuntimeコードはEditorコードを参照できないというルールがあります。

これ、最初はかなりハマりやすいです。

たとえばこんな状態ですね。

• Runtime asmdef → Editor asmdef を参照
• 通常スクリプトで UnityEditor 名前空間を using
• Editorフォルダ内コードをRuntimeから呼ぶ

UnityEditor系は、Unityエディタ上でしか存在しない機能です。

そのため、実機ビルドに含まれるRuntimeコードから参照すると、依存関係が破綻します。

特に「Editorフォルダに移動しただけ」でasmdef設定を見直していないケースはかなり多いです。

アセット導入直後に発生した場合も、内部でEditor/Runtime分離されている可能性があります。

asmdef名変更で参照が切れた

asmdefの名前変更も、意外と危険ポイントです。

特に「Use GUID」を使っていない場合、参照が名前ベースで管理されます。

すると、こんな事故が起きます。

• asmdef名を変更
• 参照側が旧名を探す
• Missing発生

Git管理しているチーム開発だと、このタイプは地味に多いです。

「リファクタリングのつもりが全員コンパイルエラー」みたいなこともあります。

最近asmdef名を整理した場合は、この可能性もかなり高いですね。

Define Constraintsで参照先が除外されている

少し中級者向けですが、Define Constraintsも要注意です。

Define Constraintsは、条件付きでasmdefをコンパイル対象から外す仕組みです。

たとえばこんな条件があります。

• 特定Packageが存在する時だけ有効
• 特定Platformだけ有効
• シンボル定義時のみ有効

つまり、asmdef自体は存在していても、現在の条件ではコンパイルされていないことがあります。

この状態でも、参照側から見ると「Missing」に見えるんですね。

---

Assembly definition references missing の直し方

ここからは、実際にエラーを直す流れを整理していきます。

asmdef関連は、やみくもに触るより「どの参照が壊れているか」を順番に確認した方が圧倒的に早いです。

私も昔、Library削除や再インポートを繰り返して遠回りしましたが、結局Inspector確認が最短でした🙂

手順① Missingになっているasmdefを特定する

まずはConsoleを確認します。

エラーをダブルクリックすると、対象の.asmdefファイルへ移動できることが多いです。

asmdefを選択したら、Inspectorの次の項目を確認してください。

• Assembly Definition References
• Platforms
• Define Constraints

特に重要なのが「Assembly Definition References」です。

ここに Missing と表示されている参照が、現在のエラー原因です。

まずは「どの参照がMissingなのか」を把握しましょう。

逆に、ここを確認せずにasmdefを削除し始めると、依存構造そのものを壊してしまうことがあります。

手順② Missing参照を「削除していいか」判断する

Missingが見つかったら、次は「削除していい参照なのか」を判断します。

ここ、かなり大事です。

というのも、不要参照なら削除で解決しますが、本来必要な依存を消すと別機能まで壊れるからです。

状況	削除してOK？
使わない古いPackage参照	OKなことが多い
現在使っている機能の依存	削除NG
Editor専用拡張の参照	構成確認が必要
Input System / Addressables	再導入を優先

迷った時は、

• そのPackageを現在使っているか
• 関連スクリプトが存在するか
• PrefabやSceneで参照されていないか

を確認すると判断しやすいです。

「消してもエラー減らないな…」という場合は、別asmdefが連鎖的に依存していることもあります。

手順③ Packageを再インストールする

必要なPackage依存だった場合は、Package Managerから再インストールします。

特に多いのはこのあたりです。

• Input System
• Addressables
• Localization
• TextMeshPro関連
• アセットストア製ツール

Package Managerで復旧しない場合は、manifest.json側で依存が崩れているケースもあります。

また、アセットによっては再Importが必要になることもあります。

セーブ系やEditor拡張系は依存が複雑になりやすいので、Package整理時は慎重に進めるのがおすすめです。

Easy Save のような大規模アセットも、内部でasmdef分割されていることがあります。

手順④ Runtime/Editor構造を修正する

Package問題ではなく、Editor/Runtime構造ミスの場合もかなり多いです。

特に次の状態は要注意です。

• Runtime asmdef → Editor asmdef を参照
• Runtimeコードで UnityEditor using
• Editor専用コードを通常フォルダへ配置

この場合は、Editorコードを分離します。

基本構成はこんな感じです。

• Runtimeコード → 通常フォルダ
• Editorコード → Editorフォルダ
• Editor専用asmdef → PlatformsをEditor限定

特にasmdef導入後は、「Editorフォルダへ移動しただけ」では解決しないことがあります。

---

Unity asmdefのEditor/Runtime分離ルール

asmdef周りで長くハマりやすいのが、EditorとRuntimeの分離です。

特に「UnityEditorを使っただけなのに突然コンパイルエラー」というケース、かなり多いんですよね。

ここはUnity特有のルールなので、一度整理しておくと後からかなり楽になります。

RuntimeはEditorを参照できない

Unityには、次のような依存ルールがあります。

• Editor → Runtime はOK
• Runtime → Editor はNG

つまり、ゲーム本編側のコードから、UnityEditor系コードを参照してはいけません。

なぜかというと、UnityEditor名前空間は「Unityエディタ上でしか存在しない機能」だからです。

たとえば次のようなコード。

using UnityEditor;

これはInspector拡張やEditorWindowでは普通に使います。

でもRuntime側に入ると、ビルド時に存在しないライブラリを参照することになります。

その結果、asmdef依存が壊れて「references missing」やビルドエラーにつながるわけですね。

特にasmdef導入後は、Unityが自動で吸収してくれなくなる部分も増えるので、依存方向を意識することがかなり大切です。

初心者がやりがちな危険パターン

実際によくあるのは、こんなパターンです。

• 便利そうなEditorコードをRuntimeフォルダへ置く
• Editorフォルダへ移動しただけで安心する
• Runtime asmdefからEditor asmdefを参照する
• #if UNITY_EDITOR を入れれば全部OKだと思う

最後の「#if UNITY_EDITOR」は特に誤解されやすいです。

条件分岐でコード自体は除外できますが、asmdef依存構造までは無効化されません。

つまり、

• コードは無効
• でもasmdef参照は残っている

という状態になることがあります。

なので、「コンパイル条件を書いたのにMissingが消えない」という時は、asmdef側を確認する必要があります。

また、アセットストア製ツールを導入した時も要注意です。

Editor拡張とRuntimeコードが分離されているアセットでは、asmdef構成が複雑なことがあります。

安全なフォルダ構成の例

asmdef管理で安定しやすいのは、最初から役割を分ける構成です。

Scripts/
├─ Runtime/
│  ├─ Gameplay
│  └─ UI
│
├─ Editor/
│  ├─ Inspectors
│  └─ Tools
│
└─ Tests/

この形にしておくと、

• Runtime依存
• Editor依存
• テストコード

を分離しやすくなります。

特にチーム開発では、「どこへコードを置くべきか」が明確になるので、asmdef事故がかなり減ります。

フォルダ設計を見直したい場合は、こちらの記事も参考になります。

---

Unity asmdefで「Use GUID」を使うべき理由

asmdefを使い始めた頃は、意外と見落としやすいのが「Use GUID」です。

でも、プロジェクト規模が少し大きくなると、この設定の有無でトラブル率がかなり変わります。

特にasmdef名を整理したり、チーム開発をしている場合は重要です。

名前参照だとリネーム時に壊れる

Use GUIDを使っていない場合、asmdef参照は「名前」で管理されます。

つまり、こういう状態です。

• Gameplay.asmdef
• UI.asmdef → Gameplay を参照

この時、Gameplay.asmdef の名前を変更すると、参照側が古い名前を探してしまいます。

結果として、Missingエラーになります。

特に危険なのは、後からasmdef整理を始めたタイミングです。

「名前をキレイに揃えよう」と変更した結果、依存していたasmdefが一斉にMissingになることがあります。

しかも、参照数が多いと原因特定がかなり大変です。

Git管理しているチームだと、マージ時にasmdef変更が混ざって事故になることもあります。

GUID参照なら名前変更に強い

Use GUIDを有効にすると、参照が「名前」ではなく「GUID（内部ID）」で管理されます。

そのため、asmdef名を変更しても、GUIDが同じなら参照が維持されます。

かなり地味な設定なんですが、長期運用では効果が大きいです。

設定場所は、asmdefのInspector内にあります。

• Assembly Definition References
• Use GUID

特にこんなプロジェクトでは、GUID参照の恩恵を感じやすいです。

• asmdef数が多い
• アセット導入が頻繁
• フォルダ整理をよく行う
• チーム開発している

逆に、小規模プロジェクトでは気付きにくいので、「後から事故るタイプ」の設定とも言えますね。

既存プロジェクトで切り替える時の注意点

ただし、途中からGUID運用へ切り替える場合は少し注意が必要です。

asmdef同士の参照数が多いと、変更タイミングによって一時的に参照エラーが出ることがあります。

また、アセットストア製Package側asmdefとの組み合わせでは、Package更新時に構造が変わるケースもあります。

そのため、既存プロジェクトで切り替える場合は、次の流れがおすすめです。

1. Gitやバックアップを取る
2. asmdef依存を整理する
3. Use GUIDを段階的に有効化する
4. Consoleエラーを都度確認する

特に「全部一気に変更」は、依存構造が見えなくなりやすいので注意してください。

---

Assembly Definition Reference と asmdef の違い

asmdefを触っていると、途中で「Assembly Definition Reference（asmref）」も出てきます。

名前がかなり似ているので混乱しやすいんですが、この2つは役割が違います。

ここを理解しておくと、「どこで新しいアセンブリを作るべきか」が判断しやすくなります。

asmdefは「新しいアセンブリを作る」

Assembly Definition（asmdef）は、フォルダ内スクリプトを新しいアセンブリとして分離するための設定です。

たとえばこんな感じですね。

Scripts/
├─ Gameplay/
│  └─ Gameplay.asmdef
│
├─ UI/
│  └─ UI.asmdef

この状態では、GameplayとUIが別アセンブリになります。

つまり、依存関係を明示しない限り、お互いのコードへアクセスできません。

その代わり、次のメリットがあります。

• コンパイル時間短縮
• 依存関係の整理
• Editor/Runtime分離しやすい
• Package化しやすい

大規模化するほど恩恵が大きくなります。

逆に、asmdefを増やしすぎると依存管理が複雑になるので、「分割すればするほど正義」というわけでもありません。

asmrefは「既存アセンブリに参加する」

一方、Assembly Definition Reference（asmref）は、新しいアセンブリを作りません。

既存asmdefへ「このフォルダも含めてね」と参加させるための設定です。

イメージとしてはこんな感じです。

Gameplay.asmdef
↑
asmref
↑
ExtraScripts/

つまり、ExtraScriptsフォルダのコードもGameplayアセンブリとして扱われます。

この仕組みは、フォルダ構造を整理したい時に便利です。

たとえば、

• 機能別にフォルダを分けたい
• 外部アセットを整理したい
• 既存asmdefへ後から参加させたい

みたいなケースですね。

逆に、「新しい依存分離を作りたい」用途ではasmrefは向いていません。

どちらを使うべきか判断基準

迷った時は、まず「アセンブリを分けたいのか？」で考えると判断しやすいです。

やりたいこと	向いているもの
新しい依存分離を作る	asmdef
既存アセンブリへ参加させる	asmref
コンパイル時間を分離したい	asmdef
フォルダ整理したい	asmref

特に初心者の頃は、「とりあえずasmdefを増やす」方向へ行きがちです。

でも実際は、asmrefで十分なケースもかなりあります。

---

Unity asmdefでやってはいけない設定ミス

asmdefは便利なんですが、設計を間違えると「コンパイル時間短縮どころか管理コスト爆増」になりがちです。

特に最初の頃は、「分割した方が良さそう」で増やしてしまいやすいんですよね。

ここでは、実際によくある危険パターンを整理しておきます。

asmdefを大量に分割しすぎる

asmdefは、分割すればするほど良いわけではありません。

むしろ細かく分けすぎると、依存関係の管理がかなり複雑になります。

たとえばこんな状態。

• UI用asmdef
• Button用asmdef
• Popup用asmdef
• Utility用asmdef
• Common用asmdef

最初は整理されているように見えるんですが、後から依存が絡み始めると地獄になりやすいです。

特にCommon系asmdefは、気付くと全員が参照している「巨大依存ハブ」になりがちです。

asmdef分割は、まず次の単位くらいから始めるのがおすすめです。

• Runtime
• Editor
• External Packages
• Tests

「コンパイルを分けたい理由」が明確になってから細分化した方が、かなり管理しやすくなります。

とりあえず全部参照する

asmdefを作り始めた頃、かなりやりがちなのがこれです。

エラーが出る
↓
必要そうなasmdefを全部Referencesへ追加
↓
一旦動く

……でも、この状態は後から危険です。

なぜなら、依存方向が整理されないまま増殖していくからです。

特に怖いのが循環依存ですね。

• A → B を参照
• B → A を参照

この状態になると、設計自体が崩れ始めます。

また、「どの機能が何に依存しているか」が見えなくなるので、Package削除時にも事故りやすくなります。

asmdef参照は、「本当に必要な依存だけ追加する」くらいがちょうど良いです。

EditorコードをRuntimeに混ぜる

これはasmdefトラブルの定番です。

特に便利系コードを書いた時、ついやりがちなんですよね。

たとえばこんなケースです。

• カスタムInspector用コード
• EditorWindow
• 自動セットアップツール
• ビルド支援コード

これらをRuntime側へ置くと、UnityEditor依存が混ざります。

すると、

• references missing
• ビルド失敗
• 特定Platformだけエラー

などが発生しやすくなります。

「Editorフォルダへ移動したからOK」と思いがちですが、asmdef側のPlatforms設定まで確認するのが大切です。

Package削除前に依存確認しない

Package整理時もかなり危険ポイントです。

特にアセットストア製ツールは、内部でasmdef参照が複雑になっていることがあります。

その状態で「使ってないから削除」で進めると、別機能が巻き込まれることがあります。

実際、

• Input System削除
• Addressables削除
• Editor拡張削除

あたりは、依存事故が起きやすいです。

古いアセット整理をする場合は、こちらの記事も参考になります。

Packageを削除する前に、

• asmdef参照
• Prefab依存
• Scene依存
• コード参照

を確認しておくと、「突然大量Missing」はかなり防ぎやすくなります。

---

Unity「Assembly definition references missing」まとめ

「Assembly definition references missing」は、Unityが壊れたというより、asmdefの依存関係が崩れているサインであることがほとんどです。

特に多いのは、次の4パターンでした。

• Package削除による依存切れ
• Runtime → Editor参照
• asmdef名変更によるリンク切れ
• Define Constraintsによる除外

そして、最優先で確認するべきなのは、Inspector内の「Assembly Definition References」です。

ここでMissing参照を確認すると、かなりの確率で原因を絞り込めます。

逆に、原因を見ずにasmdef削除やLibrary削除を始めると、依存構造そのものを壊してしまうことがあります。

特にasmdefは、プロジェクト規模が大きくなるほど「設計」が重要になります。

最初は便利そうに見える設定でも、

• 依存追加しすぎ
• Editor混在
• asmdef分割しすぎ
• GUID未使用

あたりが積み重なると、後からかなり管理が大変になります。

私自身も、asmdefを「なんとなく」で増やしていた頃は、Package更新のたびにMissing祭りになっていました……。

でも、

• Runtime / Editorを分ける
• 依存方向を意識する
• GUID参照を使う
• 不要参照を増やしすぎない

このあたりを整理してからは、かなり安定しやすくなりました。

もし最近、

• アセット導入が増えている
• Editor拡張を書き始めた
• コンパイル時間が長い
• asmdefエラーが頻発する

という状態なら、一度asmdef構成そのものを見直してみるのもおすすめです。

Editor拡張やasmdef運用をさらに整理したい場合は、こちらの記事も役立ちます。

---

よくある質問（FAQ）