기술 자료

Unity 엔진

Unity 엔진

프로덕션 웹 빌드 디버깅

외부 심볼, JavaScript 오류 핸들러, 스택 추적 매핑을 사용하여 배포된 웹 빌드를 디버깅합니다.
읽는 시간 2분최근 업데이트: 9일 전

외부 심볼, JavaScript 오류 핸들러, 스택 추적 매핑을 사용하여 배포된 웹 빌드를 디버깅합니다.
Unity 웹 빌드는 전체 소스 레벨 디버깅을 지원하지 않습니다. 하지만 일부 디버깅 정보를 보존하고 브라우저 오류 리포트를 사용하여 배포된 빌드의 런타임 오류를 조사할 수 있습니다.

외부 기호 사용

웹 빌드(메뉴:
플레이어 설정

?

> Publishing Settings > Debug Settings > External)에서 함수 이름을 프로덕션 스택 추적에 포함하려면 외부 심볼을 활성화합니다. 외부 심볼로 빌드하는 경우 Unity 메인 빌드 출력과 별도로 심볼 파일을 생성합니다.
잡히지 않은 JavaScript 예외가 발생하면 Unity 외부 기호 데이터를 사용하여 WebAssembly 스택 프레임을 IL2CPP 생성 C/C++ 함수 이름으로 다시 매핑할 수 있습니다. 이러한 이름은 원래 C# 클래스와 메서드를 식별하기에 충분히 읽을 수 있는 경우가 많습니다.
예를 들어,
PlayerController.Jump()
와 같은 C# 메서드는 스택 추적에
PlayerController_Jump_m<hash>
로 표시될 수 있습니다.
외부 기호를 사용하여 정확한 소스 라인이 아닌 오류가 발생한 함수를 식별합니다.

C# 이름을 더 정확하게 맵 스택 추적

더 정확한 매핑이 필요한 경우 Unity는 빌드 프로세스 중에
MethodMap.tsv
파일도 생성합니다. 이 파일은 IL2CPP가 생성한 메서드 이름을 원래 C# 메서드 이름으로 다시 매핑하는 데 도움이 되며, 이는 과부하 메서드에 특히 유용합니다.
Unity는 빌드 출력 디렉토리에 자동으로
MethodMap.tsv
를 복사하지 않습니다. 다음에서 찾을 수 있습니다.
Library/Bee/artifacts/WebGL/il2cppOutput/cpp/Symbols

제한

외부 심볼에는 다음이 포함되지 않습니다.
  • 정확한 C# 소스 파일 이름
  • 정확한 C# 줄 번호
  • 프로덕션 웹 빌드에서 C# 코드를 행별로 진행하는 기능

빌드 크기 및 런타임 영향

Unity 오류 조사에만 필요한 외부 기호 파일을 메인 빌드와 별도로 저장합니다. 즉, 외부 기호 파일은 사용자의 초기 애플리케이션 다운로드에 영향을 주지 않습니다.
기호 파일은 일반적으로 약 1~2MB이며 구축된 빌드 아티팩트와 함께 저장할 수 있습니다.
Unity 메인 빌드 출력과 별도로 외부 기호 파일을 저장하므로 이 접근 방식은 프로덕션 빌드의 초기 다운로드 크기와 런타임 성능에 거의 영향을 미치지 않습니다.

브라우저 오류 리포트

배포된 웹 빌드에서 오류 리포트를 수집하려면 Unity 콘텐츠를 호스팅하는 페이지에 JavaScript 오류 핸들러를 추가하고 Analytics 또는 크래시 리포트 서비스에 결과를 보냅니다.
유용한 브라우저 후크는 다음과 같습니다.
  • window.onerror
  • window.addEventListener('error', ...)
  • console.error
이러한 후크는 다음을 캡처할 수 있습니다.
  • 잘못된 JavaScript 예외
  • 일부 WebAssembly 런타임 오류
  • 브라우저 오류 리포트를 통해 나타나는 일부 엔진 오류
이러한 리포트를 외부 기호와 결합하여 프로덕션 스택 추적을 더 쉽게 읽을 수 있습니다.

추가 리소스