Unity 협업 중 프리팹 충돌 및 .meta 파일 관련 트러블 슈팅

내일배움캠프 27일차 TIL

❓ 문제 상황

Unity 프로젝트를 팀으로 협업하며 Git을 통한 버전 관리를 진행하던 중, 프리팹(prefab) 충돌 문제와 메타파일(.meta) 관련 문제가 반복적으로 발생했다. 특히 기능 구현이 활발히 진행되는 중반 이후부터 충돌 빈도가 급격히 증가했고, 충돌 해결에 소요되는 시간이 개발 속도에 직접적인 영향을 주었다.

 

📌 문제의 원인 분석

1. Git의 작동 방식과 Unity 프리팹의 구조적 한계

Git은 버전 관리를 할 때 파일의 변경 내용을 줄 단위(diff) 로 비교하여 변경사항을 추적한다. 이는 텍스트 파일(ex: 코드 파일)에는 적합하지만, Unity의 .prefab이나 .unity 씬 파일처럼 YAML 기반의 복잡한 구조를 가진 파일에는 비효율적일 수 있다.

 

Unity의 프리팹은 내부적으로 계층 구조(hierarchy) 를 가진 YAML 파일이다. 예를 들어 UI 프리팹에서 Button을 추가하거나 Text의 위치만 살짝 변경해도, 해당 노드뿐 아니라 그 부모-자식 관계까지 영향을 받아 여러 줄에 걸쳐 수정(diff) 이 발생한다. Git 입장에서는 서로 다른 위치를 수정했더라도 전체 블록이 수정된 것처럼 보이며, 충돌(conflict)로 간주한다.

 

🔸 예시 상황

A의 변경	B의 변경	병합 시 Git의 인식
새로운 오브젝트(Button) 추가	기존 오브젝트 위치 이동	둘 다 prefab 파일 전체에 diff 발생 → 충돌 발생

 

결과적으로, 두 작업이 서로 무관해도 Git은 YAML 트리 전체를 비교하며 충돌을 발생시킴.
Unity는 병합된 YAML 결과를 정확히 인식하지 못해 프리팹이 깨지거나 사라지기도 함.

 

 

2. Unity의 .meta 파일 시스템과 GUID 의존 구조

Unity는 각 에셋에 대해 .meta 파일을 자동 생성하며, 여기에는 해당 에셋의 GUID (Global Unique Identifier; 글로벌 고유 식별)와 타입 정보, 임포트 설정 정보 등이 저장된다. .meta 파일은 에셋이 삭제되거나 이동해도 GUID를 통해 참조를 유지하기 위한 핵심 요소다.

 

Git 관리에서 .meta 파일을 함께 커밋하지 않거나, 충돌이 발생한 채 병합을 하면 다음과 같은 문제가 발생한다.

• Unity는 새로운 GUID를 생성하여 .meta 파일을 덮어씀
• 기존 씬, 프리팹, 스크립트 등에서 해당 에셋을 찾을 수 없게 됨
• Unity 에디터에서는 "Missing Prefab", "Missing Script", "None (GameObject)" 와 같은 문제가 발생

 

🔸 예시 상황

상황	결과
.meta 파일 누락	Unity가 새 GUID 생성 → 기존 참조 끊어짐
.meta 파일 병합 충돌 시 임의로 덮어씀	참조 대상이 변경되거나 사라짐
다른 사람이 만든 에셋을 받았으나 .meta 빠짐	Unity는 새 파일로 인식해 버전 충돌 발생

 

GUID는 에셋의 ID이기 때문에 충돌 시 단순히 덮어쓰면 안 되며, 병합 전 비교가 필수이다.

 

3. 프리팹 구조의 비가시성 + Unity의 비협조적 병합 도구

Unity는 기본적으로 텍스트 기반 병합 도구나 충돌 해결 도구를 제공하지 않는다. 외부 병합 도구(예: UnityYAMLMerge)를 사용하지 않으면 Git이 발생시킨 충돌을 수동으로 해결해야 한다. 그러나 .prefab은 구조적으로 복잡하고 자동 병합이 어려워, 실제로는 한쪽의 변경을 포기하거나 프리팹을 새로 만드는 경우가 많음. 그 결과 충돌 회피를 위한 불필요한 복제나 중복 작업이 발생한다.

 

요약: 문제 원인의 핵심 포인트

문제 요인	설명
Git의 줄 단위 비교	Unity YAML 구조에는 적합하지 않음 (부분 변경도 전체 변경처럼 감지)
프리팹 병합의 어려움	계층 구조가 복잡하여 충돌 시 수동 병합이 어려움
.meta 파일의 중요성	누락 또는 충돌 시 GUID 꼬임 → 참조 깨짐
Unity의 병합 지원 부족	에디터에서 충돌 시 시각적 도구 없이 직접 수정 필요

 

✅  해결을 위한 팀의 대응 전략

1. 협업 프로세스 조정

• Merge 전 항상 Pull → 최신 상태 유지
  모든 팀원이 기능 브랜치 작업 전 main 또는 dev 브랜치에서 Pull을 수행하도록 습관화
• 디스코드 채널을 통한 실시간 머지 조율
  같은 프리팹을 수정할 가능성이 있는 경우, 사전에 머지 순서와 작업 분담을 협의
• Merge 전용 브랜치 운영
  각자의 기능 브랜치를 merge-test 브랜치에 병합 후, 충돌 확인 및 테스트 → 이후 main에 최종 병합

2. 작업 방식 개선

• 프리팹 책임 분담
  각 팀원이 관리하는 프리팹을 분리하고, 가능하면 기능 단위로 나누어 재사용성 높이기
• .meta 파일 주의
  .meta 파일이 Git에 반드시 포함되도록 설정 (.gitignore 확인)
  충돌 시 덮어씌우기보다 충돌 내용을 분석하고 비교 후 병합 결정
• 자주 커밋하고 자주 푸시하기
  한 번에 많은 양을 변경하지 않고 자주 커밋하여 변경 내용을 추적하고 병합 리스크 줄이기

 

💡 느낀 점

• Unity 프로젝트는 Git 충돌 해결 경험이 중요하다. 단순히 기능 구현만이 아니라, 에셋 관리와 버전 관리에 대한 이해가 필요하다는 것을 깨달았다.
• 평소 Git 사용에 자신 있었지만, Unity 특유의 구조(YAML, meta 파일 등)로 인해 예상치 못한 문제가 발생했고, 이 경험을 통해 Unity 특화된 Git 관리 전략이 필요하다는 걸 체감했다.
• 소통과 사전 조율이 얼마나 중요한지 다시 느꼈고, 앞으로도 협업 중심 사고방식을 유지하며 개발하고 싶다.