문제 해결

이 섹션은 다음 문제에 관한 정보를 제공합니다.

오류 유형	오류 메시지
일반적인 시작 문제	- 패키지 관리자 창의 오류 메시지 - 패키지 관리자 누락 또는 창이 열리지 않음 - Unity 버전 업그레이드 이후 발생하는 문제
패키지 설치 문제	- 패키지 설치 실패 - Git URL에서 패키지를 추가할 수 없음 - 불충분한 드라이브 공간
패키지 서명 문제	- 패키지 버전에 서명이 없음 - 패키지 버전에 유효한 서명이 없음
Git 종속성 설치 중에 발생하는 문제	- ‘git’ 실행 파일을 찾을 수 없음 - git-lfs: 커맨드를 찾을 수 없음 - 저장소를 찾을 수 없음 - 사용자 이름을 읽을 수 없음: 터미널 프롬프트가 비활성화됨 - Git 버전을 업데이트할 수 없음
에셋 스토어의 에셋 패키지	- My Assets 컨텍스트에서 ‘http 리스폰스를 파싱하지 못함’
범위 지정 레지스트리	- 패키지 관리자 창에 ‘My Registries’ 누락
패키지 빌드 중에 발생하는 문제	- MonoBehaviour 누락 오류

네트워크 관련 문제가 발생한 경우 Unity 패키지 관리자 진단 툴을 실행하면 됩니다. 자세한 내용은 네트워크 문제 진단을 참고하십시오.

패키지 관리자 창의 오류 메시지

패키지 관리자는 문제가 발생하면 패키지 관리자 창에 오류 표시기를 표시합니다.

시스템 관련 문제

• 네트워크 연결 문제

  패키지 관리자가 특정 패키지와 관련이 없는 문제를 감지했을 때 오류 메시지가 상태 표시줄에 표시됩니다. 예를 들어 패키지 관리자가 패키지 레지스트리 서버에 액세스할 수 없는 경우 상태 표시줄에 다음 메시지가 표시됩니다.

  

• 오류 새로 고침 에셋(또는 오류 새로 고침 패키지)

  네트워크가 패키지 레지스트리 서버에 도달할 수 없는 경우 네트워크 연결 문제가 발생할 수 있습니다. 사용자나 시스템 관리자가 네트워크 오류를 진단하고 수정하면 상태 표시줄이 없어집니다.

  네트워크에 연결되지만 Unity 계정에 로그인하지 않은 경우 패키지 관리자는 에셋 스토어 패키지를 표시하지 않습니다. My Assets 컨텍스트를 사용하려고 하면 다음과 같이 패키지 관리자에 로그인하라는 메시지가 표시됩니다.

  

  리스트 패널 내 Sign in 버튼을 클릭하여 Unity Hub를 통해 Unity 계정에 로그인합니다.

패키지별 문제

• 로드 또는 설치 시 특정 패키지에 문제가 발생하면(예: 로드할 패키지 버전을 지정할 때) 리스트 패널에서 손상된 패키지(A) 옆에 오류 아이콘()이 표시됩니다. 어떤 문제가 있는지 확인하려면 손상된 패키지의 세부 정보 패널을 통해 자세한 오류 메시지(B)를 확인하십시오.

  

패키지 관리자 누락 또는 창이 열리지 않음

패키지 관리자 창이 화면 밖으로 이동하거나 다른 창에 가려질 수 있습니다. 이 경우 패키지 관리자 창이 열리지 않는 것처럼 보입니다. 이 경우 창 레이아웃(Window > Layouts > Default)을 재설정하고 패키지 관리자 창을 다시 엽니다.

패키지 관리자 창이 여전히 나타나지 않으면 Unity 콘솔 창을 확인하십시오.

Failed to resolve packages: The file [<project-path>/Packages/manifest.json] is not valid JSON:
  Unexpected token '}' at 44:1
  }

이 오류 메시지는 잘못된 형식의 manifest.json 파일을 나타냅니다. 또한 패키지 관리자가 파일을 파싱하지 못한 줄 번호를 알려 주므로 JSON을 수정할 수 있습니다. 이 문제를 해결하기 위해 사용할 수 있는 여러 온라인 검증기가 있습니다. 수정한 파일을 저장하면 Unity가 패키지 관리자 창을 다시 로드합니다.

Unity 에디터의 초기 버전에서 업그레이드한 경우 패키지 매니페스트 파일에 다른 문제가 있을 수 있습니다.

• 2019.3부터 manifest.json 파일에는 com.unity.package-manager-ui 패키지에 대한 레퍼런스가 포함되어서는 안 됩니다. 매니페스트의 종속성 리스트에서 다음 줄을 제거합니다.

      "com.unity.package-manager-ui": "2.1.1",
  

• 프로젝트 매니페스트가 ‘exclude’를 패키지 버전으로 사용하는지 확인합니다. 이 값은 종속성 프로퍼티에 사용되지 않는 값입니다. 이와 같은 줄이 있으면 줄 전체를 제거합니다. 패키지 관리자는 프로젝트에 종속성으로 명시적으로 포함된 패키지만 설치합니다. 따라서 해당 항목을 제거하면 패키지 관리자는 패키지를 무시하고 설치하지 않습니다.

Unity 버전 업그레이드 이후 발생하는 문제

프로젝트를 최신 Unity 버전으로 업그레이드하면 패키지 관리자가 호환되지 않는 패키지를 최신 호환 버전으로 자동으로 업데이트합니다. 그러나 패키지가 컴파일되지 않으면 패키지 관리자는 콘솔 창에 오류 메시지를 표시합니다.

이러한 메시지에 표시된 문제를 해결하려면 오류 메시지를 읽고 해결 가능한 문제를 해결하십시오. 예를 들어 패키지에 다른 패키지 또는 버전에 대한 종속성이 누락될 수 있습니다. 이 경우 패키지를 직접 설치해도 됩니다.

또한 제대로 동작할 때까지 다음과 같은 해결책을 순서대로 시도해 볼 수 있습니다.

• 프로젝트 아래에 있는 Packages 폴더를 백업한 후 삭제합니다.
• 프로젝트의 Packages 폴더에 있는 패키지 소스를 백업한 다음 삭제한 후 manifest.json 파일만 남깁니다. 그런 다음 프로젝트를 다시 로드합니다.
• 비어 있는 새 씬을 생성합니다. 패키지 관리자 창이 오류 없이 로드되면 실패한 프로젝트의 Library/PackageCache/com.unity.package-manager-ui 폴더를 새로 생성한 프로젝트의 동일한 폴더로 바꿉니다.

패키지 설치 실패

레지스트리에서 새 패키지를 설치할 수 없는 경우에는 권한 관련 문제일 수 있습니다.

다음의 캐시 폴더에 대한 전체 권한이 있어야 합니다.

• Windows(사용자 계정): %LOCALAPPDATA%\Unity\cache\upm
• Windows(시스템 계정): %ALLUSERSPROFILE%\Unity\cache\upm
• macOS: $HOME/Library/Caches/Unity/upm
• Linux: $HOME/.cache/Unity/upm

네트워크에 문제가 있을 수 있습니다. 방화벽 및 프록시 설정을 확인하십시오.

때때로 학교, 관공서 같은 기관이나 네트워크 보호 작업 공간에서는 프록시 서버를 설치하여 네트워크와 인터넷 간 트래픽을 제어하고, Unity 또는 패키지 관리자에서 인식되지 않는 고유한 서버 인증서를 사용하십시오. 네트워크 관리자에게 문의하십시오.

Git URL에서 패키지를 추가할 수 없음

저장소를 찾을 수 없음을 참조하십시오.

불충분한 드라이브 공간

설치 드라이브에 공간이 없거나 부족한 경우 다음 해결 방법을 고려해 보십시오.

• 전역 캐시의 위치를 변경합니다. 전역 캐시 위치 커스터마이즈를 참조하십시오.
• 에셋 패키지 캐시의 위치를 변경합니다. 에셋 패키지 캐시 위치 커스터마이즈를 참조하십시오.
• 레지스트리 데이터 캐시 제한의 최대 크기를 줄입니다. 전역 캐시 위치 커스터마이즈를 참조하십시오.

패키지 버전에 서명이 없음

이 메시지는 범위 지정 레지스트리에서 Unity 패키지를 가져올 때 표시될 수 있습니다. Unity는 이후 릴리스에서 반드시 다시 서명되지 않을 수 있는 예전 패키지를 제외하고 생성된 패키지에 서명합니다. 서명이 없는 Unity 패키지를 범위 지정 레지스트리에서 다른 레지스트리로 복사하면 패키지 관리자가 패키지 콘텐츠가 안전하고 원본 패키지와 동일한지 확인할 수 없습니다.

이 메시지가 표시되는 경우 다음 해결 방법을 시도해 보십시오.

• 다른 버전의 패키지를 사용합니다.
• Unity 레지스트리에서 Unity 패키지를 가져옵니다.
• 범위가 지정된 레지스트리를 가진 경우 Unity 레지스트리에서 최신 버전의 패키지를 복사해야 합니다.

패키지 버전에 유효한 서명이 없음

패키지에는 전송 전 또는 전송 중에 콘텐츠가 변경되지 않았는지 확인하는 서명이 있습니다. 일반적으로 다음 상황에서 유효하지 않은 서명이 발생합니다.

• 누군가가 자신의 레지스트리에 수정된 패키지를 퍼블리시했습니다.
• 파일을 최종 사용자에게 전송하는 중 오류가 발생했습니다.

두 경우 모두 패키지 관리자는 해당 패키지를 잠재적으로 악성인 것으로 간주합니다.

잘못된 서명을 얻으면 다른 버전의 패키지를 설치해 보십시오. 또한 Unity 레지스트리 이외의 레지스트리에서 Unity 패키지를 사용하지 마십시오.

수정 사항이 포함된 Unity 패키지를 공유하는 경우 Git URL을 사용하거나 프로젝트에 패키지를 내장하는 것이 좋습니다.

‘git’ 실행 파일을 찾을 수 없음

Git URL에서 패키지를 설치하려고 시도하면 다음과 유사한 메시지가 나타납니다.

Cannot perform upm operation: Unable to add package
[https://github.example.com/myuser/myrepository.git]:
No 'git' executable was found. Please install Git on your system and restart Unity [NotFound]
UnityEditor.EditorApplication:Internal_CallUpdateFunctions()

git-lfs: 커맨드를 찾을 수 없음

Git LFS(대용량 파일 스토리지)를 사용하는 패키지를 다운로드하려고 하면 다음 오류 메시지가 표시될 수 있습니다.

Error when executing git command. git-lfs filter-process: command not found.

이는 Git LFS가 컴퓨터에 설치되어 있지 않을 수 있음을 나타냅니다. 확인하려면 다음 커맨드 라인을 테스트하십시오.

git lfs --version

커맨드가 다음과 같이 반환하는 경우 Git LFS가 설치되어 있는 것입니다.

git-lfs/2.8.0 (GitHub; darwin amd64; go 1.12.7)

설치되어 있지 않으면 Bitbucket GitHub 지침에 따라 설치하면 됩니다.

저장소를 찾을 수 없음

패키지 관리자가 지정한 저장소를 찾을 수 없는 경우 다음과 같은 오류 메시지가 Unity 콘솔에 표시됩니다.

Cannot perform upm operation: Unable to add package [https://mycompany.github.com/gitproject/com.mycompany.mypackage.git]:
  Error when executing git command. fatal: repository 'https://mycompany.github.com/gitproject/com.mycompany.mypackage.git/' not found
 [NotFound]
UnityEditor.EditorApplication:Internal_CallUpdateFunctions() (at /Users/builduser/buildslave/unity/build/Editor/Mono/EditorApplication.cs:310)

철자를 확인하십시오. 올바른 URL을 사용하고 있는지 확인하려면 저장소의 페이지로 이동한 후 Clone 버튼으로 URL을 복사하십시오.

GitHub(A) 또는 GitLab(B)에서 URL 오른쪽에 있는 버튼을 클릭하여 URL을 클립보드에 복사합니다.

저장소의 위치가 정확하다면 URL에 다른 문제가 있을 수 있습니다.

• 특정 리비전을 타게팅하는 경우 리비전이 끝에 표시되는지 확인합니다. 예시:
  https://github.example.com/myuser/myrepository1.git#revision
• 한 리비전을 타게팅하고 패키지가 루트에 없는 경우, path 쿼리 파라미터가 리비전 앵커 앞에 있는지 확인합니다. 예시:
  https://github.example.com/myuser/myrepository.git?path=/example/folder#v1.2.3

저장소 위치와 URL이 올바른 경우, PATH 시스템 환경 변수를 확인합니다. PATH 변수에 Git cmd 디렉토리(Windows)와 Git bin 디렉토리(Windows, macOS)의 항목이 포함되어 있는지 확인합니다. 패키지 관리자 프로세스에는 PATH 변수에 이러한 항목이 필요합니다.

사용자 이름을 읽을 수 없음: 터미널 프롬프트가 비활성화됨

인증이 필요한 프라이빗 저장소에서 패키지를 설치하려고 하면 다음과 유사한 메시지가 [Unity 콘솔]에 나타납니다.

Cannot perform upm operation: Unable to add package [https://mycompany.github.com/gitproject/com.mycompany.mypackage.git]:
  Error when executing git command. fatal: could not read Username for 'https://mycompany.github.com': terminal prompts disabled
 [NotFound]
UnityEditor.EditorApplication:Internal_CallUpdateFunctions() (at /Users/builduser/buildslave/unity/build/Editor/Mono/EditorApplication.cs:310)

일반적으로 이 메시지는 HTTP에 대한 사용자 이름과 비밀번호를 입력하거나 SSH 키를 잠금 해제하기 위한 패스프레이즈를 입력할 수 있는 대화형 터미널 또는 다이얼로그를 패키지 관리자가 제공하지 않기 때문에 표시됩니다.

• HTTP(S)를 사용하면 Bitbucket, GitHub, GitLab에 로그인할 때마다 터미널이나 다이얼로그에 사용자 이름과 비밀번호를 입력해야 합니다. 하지만 패키지 관리자는 HTTP(S)에 대한 사용자 이름과 비밀번호를 입력할 수 있는 대화형 터미널이나 다이얼로그를 제공하지 않습니다.

  이 문제를 우회하려면 HTTPS에 대한 해결 방법에서 제안한 해결 방법 중 하나를 시도해 보십시오.

• SSH는 공용 SSH 키와 비공개 SSH 키를 사용합니다. Bitbucket, GitHub, GitLab에 공용 SSH 키를 추가한 다음, 사용자 이름과 암호를 입력하지 않아도 저장소에 액세스할 수 있습니다.

  하지만 SSH 키를 안전하게 유지하기 위해 패스프레이즈를 설정한 경우 키를 인증하려면 터미널이나 다이얼로그에 해당 패스프레이즈를 입력해야 합니다. 이 경우 SSH 키를 잠금 해제하여 패키지 관리자로 인증할 수 있는 SSH 에이전트를 사용하면 됩니다.

HTTPS에 대한 해결책

패키지 관리자는 HTTP(S) 사용자 이름과 비밀번호를 입력할 수 있는 대화형 터미널이나 다이얼로그를 제공하지 않습니다. 이를 우회하려면 다음 해결 방법 중 하나를 사용하십시오.

• HTTPS Git URL로 비공개 저장소 사용 및 SSH Git URL로 비밀번호 보안 SSH 키 사용 지침을 따르십시오.
• 자격 증명 관리자(Windows용 Git 자격 증명 관리자 또는 OSXKeyChain)를 사용합니다. 자격 증명 관리자는 터미널이나 커맨드 프롬프트를 사용하지 않고도 비밀번호 전송을 처리합니다.
• 터미널이나 커맨드 프롬프트에서 git-credentials를 사용한 다음, 동일한 터미널에서 Hub를 실행하여 Unity가 캐시된 자격 증명 또는 저장된 자격 증명에 액세스할 수 있도록 합니다.
• 대신 SSH를 사용하여 인증합니다. 패스프레이즈가 없는 SSH 키를 설정하는 경우 패키지 관리자는 Git 서버로 인증하기 위해 SSH 키를 암호화 해제할 필요가 없습니다. 보안을 강화하기 위해 비밀번호를 사용하기로 결정한 경우 macOS 또는 Windows에서 ssh-agent를 사용하여 인증 문제를 피할 수 있습니다.

SSH에 대한 해결책

SSH 프로토콜을 사용하여 Git URL을 통해 패키지를 설치하는 경우 Git에서 인증 오류가 발생할 수 있습니다. 이는 일반적으로 패스프레이즈로 보호한 로컬 컴퓨터에서 비공개 SSH 키를 설정할 때 발생합니다.

이 문제에 대한 해결 방법은 SSH 키를 잠금 해제할 수 있는 SSH 에이전트를 설정하여 패키지 관리자가 사용자를 대신하여 인증하도록 만드는 것입니다. 다음 중 해당 운영 체제 섹션의 지침을 따르십시오.

• Windows용 OpenSSH 설정
• macOS용 SSH 에이전트에 SSH 키 추가

Windows용 OpenSSH 설정

빌트인 Windows OpenSSH 버전의 ssh-agent는 Windows용 Git에서 기본적으로 제공되는 버전보다 더 잘 작동합니다. 이 절차에서는 OpenSSH 클라이언트를 설정하고 해당 ssh-agent에 키를 추가하는 방법을 설명합니다. Windows용 Git을 사용하는 경우 빌트인 Windows OpenSSH를 Windows용 Git SSH 에이전트보다 우선시할 수도 있습니다.

1. OpenSSH 클라이언트가 설치되어 있는지 확인합니다. 이를 확인하려면 Windows Settings Optional features 창(Start > Settings로 이동한 다음 ‘Optional features’ 검색)에서 검색합니다. 이는 Windows 10 이상에 적용됩니다.

2. %PATH% 환경 변수를 확인하여 빌트인 Windows OpenSSH 위치가 표시되는지 확인합니다(예: C:\WINDOWS\System32\OpenSSH\).

   참고: 이미 Windows용 Git을 사용하고 있는 경우, %PATH% 변수의 Windows용 Git SSH 위치 앞에 빌트인 Windows OpenSSH 위치가 표시되는지 확인합니다. 이렇게 하면 Windows가 Windows용 Git SSH 에이전트를 통해 빌트인 Windows OpenSSH 에이전트를 사용하는지 확인할 수 있습니다.

3. PowerShell 터미널에서 ssh-agent 프로세스를 시작하여 다음과 같이 자동으로 시작되는지 확인합니다.

   # Set the ssh-agent service to start automatically and manually start it now
   Get-Service ssh-agent | Set-Service -StartupType Automatic
   # Run the ssh-agent process to start the ssh-agent service
   ssh-agent
   

4. 키를 ssh-agent로 임포트합니다. 이렇게 하려면 커맨드 라인에서 ssh-add를 실행한 다음 지침을 따르십시오. 기본적으로 에이전트는 %USERPROFILE%\.ssh\id_rsa 키를 추가하고 비밀번호를 입력하라는 메시지를 표시합니다.

   # Import the key
   ssh-add
   

   다른 키를 사용하려면 다음을 인수로 지정할 수 있습니다.

   # Set the ssh-agent service to start automatically and manually start it now
   ssh-add <your-secure-ssh-key-name>
   

   키 이름이 기억나지 않는 경우 다음 커맨드를 사용하여 키를 나열합니다.

   ssh-add -l
   

5. Windows용 Git을 설치한 경우 %GIT-SSH% 환경 변수를 초기화하여 Git이 항상 빌트인 Windows OpenSSH 버전의 ssh-agent를 사용하도록 합니다.

   [Environment]::SetEnvironmentVariable("GIT_SSH", "$((Get-Command ssh).Source)", [System.EnvironmentVariableTarget]::User)
   

macOS용 SSH 에이전트에 SSH 키 추가

ssh-add 커맨드를 사용하여 macOS 시스템에서 실행되는 ssh-agent에 SSH 키를 추가하십시오. 사용하는 커맨드 파라미터는 macOS 버전에 따라 다릅니다.

• macOS 11 이하에서는 다음을 사용하십시오.

  ssh-add -K ~/.ssh/<your-secure-ssh-key-name>
  

• macOS 12 이상에서는 다음을 사용하십시오.

  ssh-add --apple-use-keychain ~/.ssh/<your-secure-ssh-key-name>
  

이 커맨드를 실행하면 터미널이 SSH 키를 잠금 해제하기 위한 비밀번호를 요청한 후 이를 macOS 키체인에 추가합니다. 하지만 시스템을 재시작하면 ssh-agent에 저장된 모든 키가 초기화됩니다.

시스템을 다시 시작한 후 비밀번호를 다시 입력할 필요가 없도록 하려면 ~/.ssh/config 파일을 열고(찾지 못하는 경우 새로 생성) 다음을 추가하십시오.

Host *
    UseKeychain yes
    AddKeysToAgent yes
    IdentityFile ~/.ssh/<your-secure-ssh-key-name>

컴퓨터를 다시 시작하여 이러한 변경 사항을 적용하십시오.

Git 버전을 업데이트할 수 없음

저장소에서 Git 종속성을 최신 버전으로 업데이트할 수 없는 경우 잠긴 Git 종속성 때문일 수 있습니다. 저장소에서 Git 종속성을 최신 버전으로 업데이트하려면 Add package from Git URL 버튼을 사용하여 Git URL을 입력하십시오. 자세한 내용은 잠긴 Git 종속성을 참조하십시오.

My Assets 컨텍스트에서 ‘Http 리스폰스를 파싱하지 못함’

에셋 스토어에서 패키지를 다운로드하려고 할 때 콘솔 창에 다음 메시지가 표시되는 경우 에셋 패키지 캐시에 문제가 있을 수 있습니다.

[PackageManager] Error Failed to parse response. UnityEditor.AsyncHTTPClient![:D](https://forum.unity.com/styles/default/xenforo/clear.png)one(State, Int32)

이 문제를 해결하려면 다운로드한 에셋 패키지 파일 위치에서 다운로드한 에셋을 모두 삭제한 후 에셋을 다시 다운로드하십시오.

경고: 프로젝트에 에셋 데이터가 많은 경우 모든 에셋을 다시 다운로드하는 데 많은 시간과 대역폭이 소요될 수 있습니다.

패키지 관리자 창에 ’My Registries’가 없음

모든 레지스트리 공급자가 Unity의 패키지 관리자와 호환되는 것은 아닙니다. 추가한 패키지 레지스트리 서버가 /-/v1/search 또는 /-/all 엔드포인트를 구현하지 않는 경우, 범위 지정 레지스트리는 Unity의 패키지 관리자와 호환되지 않으며, 패키지 관리자 창의 내비게이션 패널에서 My Registries 아래에 표시되지 않습니다.

MonoBehaviour 누락 오류

빌드 중에 누락 동작에 대한 오류가 많이 발생하면 UnityLinker가 참조되지 않은 컴포넌트를 실수로 스트리핑한 것일 수 있습니다. 스트리핑 레벨이 너무 높게 설정되어 있기 때문에 이런 오류가 발생하는 경우가 많습니다. 예를 들어 AssetBundle에 있는 프리팹이 2D SpriteShape 패키지의 SpriteShape 컴포넌트를 참조하는 경우 오브젝트가 누락되어 컴파일러 경고가 발생할 수 있습니다.

이를 해결하려면 UnityLinker에 대한 스트리핑 레벨을 낮추거나 link.xml 파일 내에서 패키지의 어셈블리를 선언하여 스트리핑되지 않도록 할 수 있습니다.

<linker>
    <assembly fullname="Unity.2D.SpriteShape.Runtime" preserve="all"/>
    <assembly fullname="Unity.2D.Common.Runtime" preserve="all"/>
 </linker>

스트리핑 레벨과 UnityLinker에 대한 자세한 내용은 관리되는 코드 스트리핑을 참조하십시오.