Version: 2021.3
스마트 병합
커맨드 라인 인자

안전 모드

개요

Unity의 안전 모드는 스크립트 컴파일 오류가 있는 프로젝트를 열 때 Unity 에디터가 전환할 수 있는 모드입니다. 안전 모드는 컴파일 오류를 해결하기 위한 최상의 환경을 제공하도록 설계되었으므로 프로젝트를 정상 상태로 빠르게 복원할 수 있습니다.

안전 모드에서 Unity는 기능이 제한된 최소 버전의 에디터 사용자 인터페이스를 제공합니다. 따라서 스크립트 관련 에셋만 임포트하고, 비스크립트 에셋(예: 모델, 머티리얼, 텍스처, 프리팹)은 임포트할 수 없습니다. 이는 안전 모드가 콘텐츠 제작이 아니라 컴파일 오류 해결을 위해서만 사용되기 때문입니다.

안전 모드는 관리되는 코드가 프로젝트 또는 해당 패키지에서 실행되도록 허용하지 않습니다. 즉 에디터 스크립트, 에셋 포스트 프로세서, 스크립트된 임포터 등과 같은 자체 스크립트가 실행되지 않습니다. 또한 안전 모드는 어셈블리 오버라이드, 그리고 BurstRoslyn 분석기를 비활성화합니다. 이렇게 하면 매우 손상된 상태의 프로젝트를 여는 경우에도 안전 모드의 에디터가 항상 완전히 정상적이고 안정적으로 작동합니다.

Unity는 컴파일 오류가 더 이상 없음을 감지하면 자동으로 안전 모드를 종료합니다. 안전 모드를 종료하면 Unity는 프로젝트 전체를 임포트하고, 에디터는 정상적인 전체 기능을 복원합니다.

컴파일 오류의 일반적인 원인

다음은 컴파일 오류가 발생할 수 있는 몇 가지 일반적인 시나리오입니다.

  • 예전 Unity 버전에서 최신 버전으로 프로젝트를 업그레이드합니다.
  • 프로젝트가 생성된 버전과 다른 Unity 버전에서 프로젝트를 엽니다.
  • 누락된 패키지 또는 잘못된 버전의 패키지가 있는 프로젝트를 엽니다.
  • 자체 스크립트에서 오류가 있는 프로젝트를 엽니다.
  • 최근에 가져온 변경 사항에 컴파일 오류가 포함된 버전 관리에서 프로젝트를 엽니다.

안전 모드 없이 컴파일 오류가 있는 프로젝트를 열면 여러 가지 문제가 발생할 수 있습니다. 예를 들어 프로젝트의 패키지가 제대로 로드되지 않거나 작동하지 않고, 에셋이 잘못 임포트되어 라이브러리 또는 캐시 서버에 잘못 캐싱된 결함이 발생할 수 있습니다.

이러한 경우 프로젝트의 나머지 부분이 임포트될 때까지 기다린 후 오류를 해결하고 싶지는 않을 것입니다. 안전 모드를 사용하면 이러한 스크립트 관련 문제를 직접 해결하고, 버전 관리 기능을 사용하여 프로젝트를 최신 버전으로 업데이트하여 문제를 해결할 수 있으며, 전체 프로젝트의 임포트를 기다릴 필요가 없습니다.

안전 모드 시작

컴파일 오류가 있는 프로젝트를 열면 에디터는 안전 모드를 시작할지 묻는 다이얼로그를 표시합니다.

컴파일 오류가 있는 프로젝트를 열면 Enter Safe Mode? 다이얼로그가 안전 모드를 시작할지 물어봅니다
컴파일 오류가 있는 프로젝트를 열면 Enter Safe Mode? 다이얼로그가 안전 모드를 시작할지 물어봅니다

이 때 다음의 세 가지 옵션이 제공됩니다.

  • Enter Safe Mode
  • Ignore - 오류를 무시하고 프로젝트 열기
  • Quit - Unity 종료

대개의 경우 Enter Safe Mode를 선택하여 프로젝트의 오류를 확인해야 합니다(또는 버전 관리를 사용하는 경우 오류 해결책이 포함된 변경 사항을 가져오기 위해 안전 모드를 사용해야 함). 안전 모드는 컴파일 오류 해결을 위한 최상의 환경을 제공하므로 Unity가 프로젝트의 나머지 부분을 임포트하기 전에 프로젝트를 정상 상태로 복원할 수 있습니다.

하지만 안전 모드를 시작하지 않고 싶을 때도 있습니다. 이러한 경우 Quit를 선택하여 Unity를 종료하거나, Ignore를 선택하여 오류를 무시할 수 있습니다.

참고: 이 다이얼로그는 Edit > Preferences > Asset Pipeline > Show Enter Safe Mode Dialog에서 비활성화할 수 있습니다. 이 다이얼로그를 비활성화하면 Unity가 컴파일 오류가 있는 프로젝트를 열 때 자동으로 안전 모드를 시작합니다.

안전 모드를 시작하지 않고 종료

안전 모드는 컴파일 오류를 수정하기 위해 특별히 설계되었습니다. 팀의 일원으로 Unity 프로젝트에 참여하고 있지만, 오류를 일으키는 스크립트에 대한 책임이 없고 무엇을 해야 할지 잘 모르겠다면 다이얼로그에서 Quit를 선택하고 팀의 프로그래머에게 조언을 구하십시오.

오류를 무시하고 임포트 계속하기

프로젝트를 사용 가능한 상태로 유지하지 않아도 되는 몇 가지 상황이 있습니다(예: 예전 프로젝트를 열어 일부 부분만 복사하거나, 단순히 설정 방식만 확인하려는 경우). 이 경우 오류를 무시하고 손상된 상태에서 프로젝트를 열 수 있습니다.

Ignore를 선택하고 나중에 안전 모드에서 프로젝트를 열고 싶으면 Unity를 닫은 후 다시 열어 “Enter Safe Mode” 다이얼로그에 다시 액세스하십시오.

컴파일 오류 무시가 미치는 영향

오류를 무시하기로 선택하면 Unity는 계속해서 나머지 에셋을 임포트하고 프로젝트를 완전히 엽니다. 이 경우 다음의 잠재적 결과가 발생할 수 있습니다.

  • 프로젝트가 사용 가능한 상태가 아닐 수 있습니다. 오류가 해결될 때까지 플레이 모드로 전환하거나 프로젝트 빌드를 생성하지 못할 수 있습니다. 또한 프로젝트의 모든 패키지가 올바르게 또는 전혀 로드되지 않을 수 있습니다.

  • Unity가 에셋을 두 번(실행 시 한 번, 프로젝트의 컴파일 오류를 해결한 후 한 번) 임포트해야 할 수 있습니다. 이 경우 사용 가능한 상태의 프로젝트를 로드하는 데 걸리는 시간이 늘어납니다.

  • If your project uses a Scriptable Render Pipeline, your render pipeline might not load, resulting in visual problems such as the error shader.

  • 스크립트 컴파일 오류는 프로젝트 내에서 2차 오류를 일으킬 수 있습니다. 예를 들어 컴파일 오류로 인해 프로젝트의 스크립트화된 임포터를 로드할 수 없는 경우 에셋이 잘못된 상태로 임포트될 수 있습니다.

안전 모드를 이러한 모든 문제를 방지하기 위해 설계되었습니다.

안전 모드의 에디터

안전 모드에서 Unity는 제한된 기능만 포함된 최소한의 에디터 인터페이스를 제공합니다.

안전 모드의 Unity 에디터
안전 모드의 Unity 에디터

Unity 에디터는 에디터 상단의 툴바 섹션에 표준 에디터 툴바를 대체하는 안전 모드 배너를 표시합니다. 툴바는 사용자가 안전 모드에 있음을 나타내며 Exit Safe Mode 버튼을 제공합니다. 이 버튼을 사용하면 나머지 오류를 무시하고 안전 모드를 종료할 수 있습니다. 또한 배너는 프로젝트가 프리뷰 패키지를 사용하는지 여부도 나타냅니다.

Unity 에디터는 안전 모드에서 코드 에디터와의 통합을 유지하므로, 스크립트 에셋 또는 콘솔 오류를 두 번 클릭하여 연결된 스크립트를 열고 Assets 메뉴를 통해 C# 프로젝트를 열 수 있습니다. 또한 버전 관리 시스템과의 통합도 유지됩니다.

안전 모드에서 제한된 개수의 창

에디터는 안전 모드에서 다음과 같은 제한된 개수의 창만 표시합니다.

  • 콘솔 창
  • 프로젝트 창
  • 인스펙터 창
  • 패키지 관리자 창

이러한 창들은 컴파일 오류 수정과 관련이 있기 때문에 예외적으로 사용할 수 있습니다. 안전 모드에서는 다른 창은 사용할 수 없습니다.

안전 모드의 에디터 메뉴

안전 모드에 있는 동안 에디터의 메인 메뉴에서 사용할 수 있는 옵션의 개수가 제한됩니다. 스크립트 작업과 관련된 메뉴 옵션만 보고 ​​선택할 수 있으며, 다른 콘텐츠를 만드는 등의 작업을 수행하기 위한 일반 옵션은 사용할 수 없습니다. 예를 들어 씬을 만들거나 열 수 없고, 비스크립트 에셋(예: 프리미티브 셰이프, 조명 또는 카메라)을 생성할 수 없습니다. GameObjectComponent 메뉴는 없고, Window 메뉴는 제한된 개수의 창만 제공합니다.

안전 모드에서 나타나는 제한된 에디터 메뉴에 이용 가능한 에셋 생성 옵션이 나와 있습니다.
안전 모드에서 나타나는 제한된 에디터 메뉴에 이용 가능한 에셋 생성 옵션이 나와 있습니다.

안전 모드의 프로젝트 창

안전 모드에서 프로젝트 창은 안전 모드가 아닐 때의 정상적인 동작과 몇 가지 기능적 차이가 있습니다.

가장 큰 차이점은 컴파일 관련 에셋만 선택할 수 있다는 점입니다. 다른 에셋 타입은 선택할 수 없습니다. 다른 에셋 타입은 프로젝트 창에서 회색으로 계속 표시되지만, 선택하거나 편집할 수 없습니다.

특히 상호작용할 수 있는 컴파일 관련 에셋 타입은 다음과 같습니다.

  • C# 파일(.cs)
  • DLL 파일(.dll)
  • 어셈블리 정의(.asm)
  • 리스폰스 파일(.rsp)
  • 규칙 집합 파일(.ruleset)

또한 선택 불가 에셋에 대한 아이콘은 에셋 콘텐츠의 미리보기를 표시하지 않습니다. 대신 에셋의 타입을 나타내는 일반 아이콘이 표시됩니다.

프로젝트 창에는 선택 불가 에셋에 대한 일반 아이콘이 표시됩니다.
프로젝트 창에는 선택 불가 에셋에 대한 일반 아이콘이 표시됩니다.

만들기(+) 메뉴 버튼이 비활성화되고, 프로젝트 창 컨텍스트 메뉴에서 사용할 수 있는 옵션이 줄어듭니다.

프로젝트 창의 만들기(+) 메뉴 버튼은 안전 모드에서 비활성화됩니다.
프로젝트 창의 만들기(+) 메뉴 버튼은 안전 모드에서 비활성화됩니다.

안전 모드 종료

모든 컴파일 오류를 해결하면 Unity가 자동으로 안전 모드를 종료합니다. 그런 다음 Unity는 계속해서 프로젝트를 열고 에셋을 임포트합니다.

컴파일 오류가 여전히 남은 상태에서 안전 모드를 종료하려면 안전 모드 툴바에서 Exit Safe Mode 버튼을 선택하십시오. 이는 권장되지 않으며(컴파일 오류 무시가 미치는 영향 참조), Unity는 결정을 확인하는 다이얼로그를 표시합니다.

안전 모드 툴바의 Exit Safe Mode 버튼
안전 모드 툴바의 Exit Safe Mode 버튼

프로젝트에 컴파일 오류가 여전히 남은 상태에서 안전 모드를 종료했다가 나중에 돌아오고 싶다면 Unity를 닫은 후 다시 열어 “Enter Safe Mode” 다이얼로그에 다시 액세스하십시오.

배치 모드에서의 안전 모드

배치 모드에서는 프로젝트에 컴파일 오류가 있는 경우 Unity가 자동으로 종료됩니다. 단, -ignoreCompilerErrors 커맨드 라인 인자를 사용하는 경우는 예외입니다.

스마트 병합
커맨드 라인 인자