에디터에서는 작동하는데 빌드가 실패할 때: Unity MCP로 콘솔 오류를 스크립트 및 씬 참조로 추적하기

“Unity가 에디터에서는 작동하는데 기기/빌드에서 실패한다”는 제목의 스레드는 항상 비슷합니다: Play는 정상인데 Player/기기 빌드가 빨간불이 켜지거나, 크래시가 나거나, 화면이 검게 변하거나, 씬 진입 시 NullReferenceException이 발생합니다. 엔진이 “고장난” 경우는 드뭅니다—에디터 경로가 참조 및 플랫폼 차이를 숨겼기 때문입니다: 씬이 빌드 목록에 없거나, 디스크에서 직렬화된 필드가 None이거나, 경로 대소문자 문제, 또는 UnityEditor API가 패킹 시간까지 런타임 어셈블리에 남아 있는 경우입니다.

이 글은 세 가지 축으로 구성됩니다(제목과 동일):

1. 콘솔 / 스택 → 스크립트 및 씬 오브젝트
2. 빌드 설정, Missing Script, 직렬화된 참조 확인
3. Unity MCP를 통해 Cursor에서 읽기 전용 진단 → 확인 후 최소 수정

플러그인 설치 안내나 전체 스토어 출시 가이드는 다루지 않습니다. IL2CPP 스트리핑과 네이티브 플러그인은 부록에 있습니다.

관련 자료:

• Unity MCP 설치
• Unity MCP와 Claude Code 및 Cursor 사용하기
• AI Studio HUD를 건강 이벤트에 연결하기 (올바른 연결 방법; 이 글은 “어디서 문제가 발생하는지 찾는 방법”입니다)

첫 번째: 어떤 레이어에서 실패했나요?

A. 빌드 창이 빨간색 (컴파일 / 패킹 실패)
        ↓
B. 빌드는 성공하지만 기기에서 실행 시 크래시 또는 블랙아웃
        ↓
C. 게임이 시작되지만 씬 또는 기능이 런타임에 폭발

증상	레이어	여기 먼저 확인
빌드 실패, error CS… / 타입을 찾을 수 없음	A	런타임 어셈블리가 UnityEditor를 참조하거나, 잘못된 #if, asmdef
부팅 씬에서 NRE / MissingReference	B/C	씬이 빌드 목록에 있는지, Missing Script, Inspector에서 None
Resources.Load / 추가 씬에서만 실패	C	경로 대소문자, 에셋이 패킹에 포함되었는지, 씬이 실제로 로드되었는지

Unity MCP는 열린 에디터에서 가장 강력합니다: 콘솔, Hierarchy, 컴포넌트 필드. 기기 logcat / Xcode 스택은 Cursor에 붙여넣어야 합니다—또는 Development Build를 만들어 가능하면 에디터에서 동일한 부팅 씬으로 재현하세요.

문제 해결 루프 (수동 + MCP)

수동 검토를 건너뛰고 AI에게 Player를 다시 작성하라고 요청하지 마세요.

0단계: 상황을 수동으로 고정 (~2분)

Cursor를 사용하기 전에:

1. Unity 버전과 타겟(예: Android / IL2CPP)을 기록합니다.
2. Window → General → Console을 지우고, Build 또는 Development Build를 한 번 실행합니다.
3. 첫 번째 관련 Error(스택 포함)를 복사합니다—Warning 벽은 제외합니다.
4. File → Build Settings를 엽니다: 의심되는 씬이 체크되어 있나요? 인덱스 0이 부팅 씬인가요?
5. Prefab 인스턴스를 편집했다면: Apply를 했나요? 적용되지 않은 오버라이드는 종종 디스크의 에셋에 반영되지 않습니다.

1단계: MCP 읽기 전용 콘솔 분류

이 빌드 / 마지막 Play와 관련된 Console Errors를 요약해 주세요 (Info는 무시).
컴파일 / Missing Script / NullReference / 리소스 로드로 분류하세요.
각 오류에 대해 스크립트 경로, 줄, GameObject 이름을 나열하세요.
에셋을 수정하지 마세요.

2단계: 수동 + MCP “참조 트리오”

런타임 NRE(B/C)의 경우, 스택의 오브젝트를 에디터에서 선택하고 MCP와 교차 확인하세요:

수동	MCP 프롬프트
Build Settings 목록 (스크린샷 또는 받아쓰기)	“Build Settings 씬 경로와 활성화 플래그를 나열하고 부팅 씬을 지정하세요.”
Inspector: Missing Script / None 참조	”씬 <이름>에서 Missing Script를 나열하고 <오브젝트>.<컴포넌트>의 직렬화된 필드에서 None을 확인하세요. 표로만. 편집하지 마세요.”
Prefab 에셋 vs 씬 인스턴스	”가 Prefab 에셋인지 씬 인스턴스인지 알려주세요. 보이는 경우 적용되지 않은 오버라이드가 있나요? 보고만 하세요.”

규칙: 패킹은 디스크에 있는 씬/Prefab을 사용합니다. 에디터에서 “괜찮아 보이는” 임시 OnValidate 채움은 포함되지 않습니다—MCP/Inspector의 직렬화된 값을 신뢰하세요.

3단계: 진단 템플릿, 그 다음 확인

[제약 조건]
- 진단하고 최소 계획을 제안하세요. 편집 전에 제 승인을 기다리세요.
- 대량 GameObject.Find로 가짜 수정을 하지 마세요.
- 이 오류와 관련된 스크립트/Prefab/씬만 수정하세요.

[씬]
- 에디터 Play: 정상 / 고장 (정직하게)
- 플랫폼 / 빌드: …
- Build Settings 부팅 씬: …
- 콘솔 / 기기 스택 (원본):
<paste>

[답변]
1. 레이어 A / B / C
2. 최상위 1–2가지 근본 원인 (빌드에 없음 / None 참조 / Missing Script / 대소문자 / Editor API 등)
3. 확인해야 할 오브젝트와 필드 이름
4. 최소 수정 단계 (아직 실행하지 마세요)

4단계: 최소 쓰기 + 재확인

확인된 최소 수정을 적용하세요: 이 오류에 대해 <오브젝트.필드> 또는 <스크립트 경로>의 몇 줄만.
씬/Prefab을 저장하세요.
그런 다음 읽기 전용 재확인: 필드가 여전히 None인가요? 같은 오류가 Console에 여전히 있나요?

작업 예제: 스택 → 필드

합성되었지만 현실적인 Player/기기 로그입니다 (프로젝트에 맞게 경로를 바꾸세요).

로그

NullReferenceException: Object reference not set to an instance of an object
  at HudHealthView.HandleHealthChanged (System.Single current, System.Single max) [0x00000] in Assets/Scripts/UI/HudHealthView.cs:42
  at PlayerHealth.TakeDamage (System.Single amount) [0x00000] in Assets/Scripts/Combat/PlayerHealth.cs:28
  at DebugDealDamage.Update () [0x00000] in Assets/Scripts/Debug/DebugDealDamage.cs:15

레이어

• Update에 도달 → A 아님 (컴파일 정상)
• 데미지에서 죽음 → C (런타임); UI 참조가 의심됨, “전투 재작성”이 아님

수동

1. HUD의 씬이 Build Settings에 있나요?
2. HudHealthView 오브젝트를 선택하세요. healthFill / playerHealth가 None인가요?
3. Prefab 편집: 적용했나요?

MCP

읽기 전용: HUD가 포함된 씬을 엽니다.
1. HudHealthView가 있는 오브젝트를 찾으세요.
2. healthFill, playerHealth (및 동료)가 None / Missing인지 보고하세요.
3. 편집하지 마세요.
None인 경우: 최소 계획은 참조를 다시 할당하고 저장하는 것입니다—TakeDamage를 변경하는 것이 아닙니다.

최소 수정 (승인 후)

• HUD_HealthFill Image를 healthFill로 드래그; Player의 PlayerHealth를 playerHealth로 드래그
• 저장; Development Build; 다시 데미지 가하기

잘못된 “수정” (하지 마세요)

// 안티 패턴: Find는 None을 숨깁니다—이름 변경이나 추가 로드 시 여전히 깨집니다.
healthFill = GameObject.Find("HUD_HealthFill").GetComponent<Image>();

올바른 연결: HUD → 건강 이벤트. 여기서는: 스택에서 필드를 고정한 다음 다시 바인딩하세요.

증상 매트릭스 (축)

증상 1: 빌드 빨간불 — 타입을 찾을 수 없음 / UnityEditor

가능한 원인	수동	MCP
런타임 스크립트가 Editor API 사용	파일이 Editor/ 밖에 있나요?	”Editor 폴더 밖에서 UnityEditor.를 검색하고 경로만 나열하세요.”
#if 반전, Player에 타입 없음	UNITY_EDITOR 래핑 확인	”이 파일에 대해 Editor vs Player에 어떤 타입이 존재하나요?“
asmdef 누락	실패하는 .asmdef 열기	”asmdef 참조를 나열하고 어떤 것이 누락되었나요?”

안티 패턴 (런타임 어셈블리의 Editor API → Player 빌드 실패):

using UnityEngine;
using UnityEditor; // Editor 어셈블리가 아니면 빌드 실패

public class BadBake : MonoBehaviour
{
    [MenuItem("Tools/Bad")] // 추가 UnityEditor 의존성
    static void Run() { }
}

수정 A: 전체 파일을 Editor/ 아래로

Assets/Scripts/Editor/BakeTools.cs   ← 에디터 전용 컴파일

수정 B: 파일 내에서 격리 (파일을 공유해야 하는 경우에만)

using UnityEngine;

public class RuntimeSafe : MonoBehaviour
{
    public void DoGameplay() { /* Player에 표시 */ }

#if UNITY_EDITOR
    [ContextMenu("Debug/Fill Refs")]
    void EditorOnlyFill()
    {
        // 에디터 전용 — Awake에서 패킹된 런타임 데이터로 취급하지 마세요.
    }
#endif
}

더 깔끔한 방법: Editor 전용 스크립트 + asmdef로 런타임 어셈블리가 Editor 참조를 끌어들이지 않도록 하세요.

증상 2: 씬 진입 시 기기 NRE; 에디터 Play는 “괜찮아 보임”

순서대로 확인하세요—병렬 대규모 재작성 금지:

1. 씬이 Build Settings에 없거나 부팅 씬이 잘못됨
2. Missing Script / 직렬화된 None (적용되지 않은 Prefab 포함)
3. 추가 씬이 로드되지 않음 (Find / 접근 전)
4. Resources.Load 경로 대소문자 (macOS 에디터는 종종 대소문자 구분 안 함; Android는 구분함)

1. Build Settings 씬, 활성화 플래그, 부팅 인덱스를 보고하세요.
2. 씬 <X>에서 모든 Missing Script를 나열하세요.
3. 부팅 경로를 따라 GameManager / Player / HUD의 공개 참조에서 None을 확인하세요.
보고만 하세요. 편집하지 마세요.

에디터에서	패킹에서	일반적인 원인
참조가 설정된 것처럼 보임	런타임 None	적용되지 않은 인스턴스 오버라이드; 잘못된 씬 파일 편집
Find가 작동	기기에서 null	오브젝트가 로드되지 않은 씬에 있음; 이름 불일치
Resources.Load가 작동	기기에서 null	경로 대소문자; 에셋이 Resources/ 아래에 없음

// 디스크: Assets/Resources/UI/HealthBar.png
// Android에서 종종 실패 (대소문자 불일치):
Resources.Load<Sprite>("ui/healthbar");
// Resources 아래 경로와 일치하도록, 예:
Resources.Load<Sprite>("UI/HealthBar");

Resources.Load / Addressables.LoadAssetAsync 경로 문자열을 검색하세요.
실제 상대 경로와 대소문자 구분 테이블을 만드세요. 아직 코드를 편집하지 마세요.

증상 3: Console에 Missing Script가 가득함

씬 <X>와 Prefab <경로>를 스캔하세요.
Missing Script가 있는 GameObject 경로를 나열하세요.
각 항목에 대해: 원래 스크립트를 다시 연결하거나 빈 컴포넌트를 제거하는 것을 제안하세요 (보이는 경우 남은 이름/GUID에서).
자동으로 일괄 삭제하지 마세요.

수동: 스크립트 파일이 여전히 존재하고 asmdef/GUID가 깨지지 않았는지 확인하세요; 빈 것을 삭제하기 전에 하나씩 확인하세요.

승인 체크리스트

1. Console에서 관련 Errors가 사라짐
2. 에디터 Play가 동일한 실패 경로를 따라감 (레벨 진입, 데미지, UI 열기 등)
3. 타겟으로 Development Build 한 번 (또는 로컬 Player)
4. MCP 읽기 전용 재확인: 의심 필드가 더 이상 None / Missing이 아님
5. Git diff가 예상된 작은 씬/Prefab/스크립트 변경뿐—우연한 리팩터링 없음

읽기 전용 재확인: <오브젝트 목록>에 None 또는 Missing Script가 있나요? 예외를 나열하세요. 편집하지 마세요.

프롬프트 금지선

하지 마세요	하세요
”그냥 Play가 작동하게 해줘”	레이어 A/B/C + 스택에서 필드 고정
참조 대신 대량 Find	직렬화된 필드 수정 또는 명시적 주입
요청 없이 Build Settings 재정렬	현재 목록과 부팅 씬을 먼저 보고
”NRE가 있어”	첫 20–40줄 스택 붙여넣기

제품 경계

• Unity MCP: 에디터 콘솔, Hierarchy, 스크립트, 참조—이 글의 핵심.
• AI Studio: UI 구조를 엔진에 연결; 재내보내기 후 연결 게시물에 따라 다시 바인딩—게임플레이에서 UI를 Find하지 마세요.
• 인증서, 스토어, OEM ROM: 로그 텍스트를 Cursor에 붙여넣어 읽기 도움을 받으세요; MCP 씬 편집 범위 밖입니다.

부록: 일반적이지만 축에서 벗어난 경우

이 글의 축을 먼저 배제하세요:

증상	방향
Development는 정상, Release는 죽음	Managed Stripping / link.xml; MCP: “크래시 스택에서 스트리핑된 타입을 추측하고 link.xml을 제안하세요. 아직 파일을 쓰지 마세요.”
Android 네이티브 크래시 (비관리)	.so / 권한 / Gradle; logcat을 붙여넣어 읽기
Unity API가 메인 스레드가 아님	비동기 콜백이 메인 스레드로 돌아오는지 확인

스트리핑과 Missing Script를 하나의 “대규모 재작성”으로 병합하지 마세요.

요약

1. 에디터 정상 / 패킹 실패 → 참조 / 빌드 씬 / 경로 / Editor API를 먼저 의심
2. Build Settings와 첫 Error를 수동으로 고정한 다음 MCP 읽기 전용 분류
3. 스택 → 스크립트 줄 → 컴포넌트 필드; 확인 후 다시 바인딩하거나 빈 컴포넌트 제거
4. 가짜 수정으로 Find나 게임플레이 재작성 금지
5. Development Build + 읽기 전용 재확인으로 승인

“고정 → 레이어 → 참조 트리오 → 샘플처럼 필드 고정”을 실행하면 대부분의 기기 참조 버그가 검토 가능한 작은 diff로 줄어듭니다.