本地文件夹或 tarball 路径

Diagnose network issues

故障排除

本节提供有关以下问题的信息：

错误类型：	错误消息：
一般启动问题	- Error messages in the Package Manager window - Package Manager missing or window doesn’t open - Problems after upgrading Unity to new version
包安装问题	- Package installation fails - Unable to add package from Git URL - Insufficient drive space
Package signature issues	- Package version has no signature - Package version doesn’t have a valid signature
安装 git 依赖关系时的问题	- 未找到“git”可执行文件 - git-lfs：未找到命令 - 未找到代码仓库 - 无法读取用户名：终端提示符已禁用 - 无法更新 Git 版本
Asset Store 资源包 (My Assets)	- ‘Failed to parse http response’ in My Assets context
范围注册表	- Package Manager 窗口中缺少“My Registries”
构建包时的问题	- Missing MonoBehaviour errors

You can also run the Unity Package Manager Diagnostics tool if you are experiencing problems that might be network-related. For more information, refer to Diagnose network issues.

Package Manager 窗口中的错误消息

The Package Manager displays error indicators in the Package Manager window when it encounters problems.

System-wide issues

Network connection issues

Error messages appear in the status bar when the Package Manager has detected an issue that isn’t related to a specific package. For example, if the Package Manager can’t access the package registry server, it displays this message in the status bar:

Network error message
Error refreshing assets (or Error refreshing packages)

If your network can’t reach the package registry server, it’s probably because there is a connection problem with the network. When you or your system administrator diagnose and fix the network error, the status bar clears.

If your network connection is working, but you aren’t signed into your Unity account, the Package Manager doesn’t display any Asset Store packages. When you try to use the My Assets context, the Package Manager prompts you to sign in:

Logged out of Unity account

Click the Sign in button inside the list panel to sign into your Unity account through the Unity Hub.

Package-specific issues

If a specific package has a problem when loading or installing (for example, when determining which package versions to load), the error icon () appears in the list panel next to the compromised package (A). To find out what the problem is, check the compromised package’s details panel to view the detailed error message (B):

Dependency error message

Package Manager 缺失或者窗口无法打开

Package Manager 窗口可能会移出屏幕或被另一个窗口隐藏。发生这种情况时，Package Manager 窗口似乎无法打开。在这种情况下，可以尝试重置窗口布局 (Window > Layouts > Default) 并重新打开 Package Manager 窗口。

如果 Package Manager 窗口仍未出现，请检查 Unity Console 窗口：

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

This error message indicates a malformed manifest.json file. It also tells you the line number where the Package Manager failed to parse the file, so you can fix the JSON. There are several online validators that you can use to try to correct the problem. Once you save the corrected file, Unity reloads the Package Manager window.

If you upgraded from an earlier version of the Unity Editor, there might be other problems with your package manifest file:

As of 2019.3, your manifest.json file shouldn’t contain any references to the com.unity.package-manager-ui package. Remove the following line from the manifest’s dependencies list:
```
    "com.unity.package-manager-ui": "2.1.1",
```
Check if your project manifest uses “exclude” as a package version. This is an obsolete value for the dependencies property. If you find any lines like these, remove the entire line. Package Manager only installs packages that are explicitly included as a dependency in your project, so once you remove that entry, Package Manager ignores the package and doesn’t install it.

将 Unity 升级到新版本后出现的问题

When you upgrade a project to a newer Unity version, the Package Manager automatically updates incompatible packages to newer compatible versions. However, if your package doesn’t compile, the Package Manager displays error messages in the Console window.

要处理这些消息，请阅读错误消息并尽可能解决所有问题。例如，一个包可能缺少对另一个包或版本的依赖。在这种情况下，您可以尝试自己安装该包。

您也可以按照以下顺序来尝试每个解决方案，直到找到可行的解决方案：

备份项目下的 Packages 文件夹，然后再删除该文件夹。
备份项目的 Packages 文件夹中的包来源文件，然后将它们删除，只留下 manifest.json 文件。然后尝试重新加载项目。
Create a new empty project. If the Package Manager window loads without errors, replace the Library/PackageCache/com.unity.package-manager-ui@<version> folder in the failing project with the same folder from the newly created project.

包安装失败

If you are trying to install a new package from the registry and it’s not working, it might be due to permission problems.

You must have full permissions on the cache folder:

Windows (user account): %LOCALAPPDATA%\Unity\cache\upm
Windows (system account): %ALLUSERSPROFILE%\Unity\cache\upm
macOS: $HOME/Library/Caches/Unity/upm
Linux: $HOME/.cache/Unity/upm

可能是网络存在问题。检查您的防火墙和代理设置。

Sometimes institutional environments, such as schools, government offices, or network-protected workplaces set up proxy servers to control traffic between the network and the Internet, and use their own server certificates which aren’t recognized by Unity or the Package Manager. Talk to your network administrator.

Unable to add package from Git URL

Refer to Repository not found.

Insufficient drive space

If your installation drive is out of space or low on space, consider the following solutions:

Change the location of the global cache. Refer to Customize the global cache.
Change the location of the Asset Store cache, refer to Customize the Asset Store cache location.
Reduce the maximum size of the registry data cache limit. For information, refer to Customize the global cache.

Package version has no signature

This message can appear when you fetch a Unity package from a scoped registry. Unity signs packages that it creates, except for older packages, which aren’t necessarily re-signed in later releases. If you copy an unsigned Unity package from a scoped registry to another registry, Package Manager can’t determine if the package content is safe and identical to the original package.

If you get this message, try these solutions:

Use another version of the package.
Fetch the Unity package from the Unity Registry.
If you own the scoped registry, make sure you copy the newest version of the package from the Unity Registry.

Package version doesn’t have a valid signature

Packages have a signature to ensure that the content wasn’t changed before or during transit. An invalid signature typically occurs in the following situations:

Someone published the package with modifications on their own registry.
An error occurred while transferring the file to the end user.

In both cases, Package Manager considers the package to be potentially malicious.

When you get an invalid signature, you can try to install a different version of the package. Also, avoid using Unity packages from a registry other than the Unity Registry.

If you are sharing a Unity package that has a fix, consider using a Git URL or embedding the package in your project.

未找到“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：未找到命令

If you are trying to download a package that uses Git LFS (Large File Storage), you might get this error message:

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

This indicates that Git LFS is probably not installed on your computer. To make sure, test it on the command line:

git lfs --version

Git LFS is installed if the command returns something like this:

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

否则，可以按照 Bitbucket GitHub 说明进行安装。

Repository not found

If you specify a location that doesn’t exist, a message similar to this one appears in the Unity Console:

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：

Where to copy the URL on GitHub (A) and GitLab (B)

单击 GitHub (A) 或 GitLab (B) 上 URL 右侧的按钮以将 URL 复制到剪贴板。

如果代码仓库的位置正确，则 URL 可能存在另一个问题：

If you are targeting a specific revision, make sure your revision comes last. For example:
https://github.example.com/myuser/myrepository1.git#revision
If you are targeting a revision and the package isn’t at the root, make sure the path query parameter precedes the revision anchor. For example:
https://github.example.com/myuser/myrepository.git?path=/example/folder#v1.2.3

Could not read Username: terminal prompts disabled

如果您尝试从需要身份验证的专用代码仓库安装包，则在 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)

Usually, this message appears because Package Manager doesn’t provide an interactive terminal or dialog where you can enter your username and password for HTTP, or your passphrase to unlock your SSH key:

With HTTP(S), every time you log onto Bitbucket, GitHub, or GitLab you need to enter your username and password in a terminal or a dialog. However, the Package Manager doesn’t provide an interactive terminal or dialog where you can enter your username and password for HTTP(S).

若要绕过此问题，请使用适用于的 HTTPS 解决方案中建议的解决方法之一。
SSH uses a pair of public and private SSH keys. You can add your public SSH key to Bitbucket, GitHub, or GitLab and then access repositories without having to enter a username and password.

However, if you have set up a passphrase to keep your SSH key safe, you still have to enter that passphrase in a terminal or a dialog to authorize your key. In that case, you can use an SSH agent that can unlock your SSH key to authenticate with the Package Manager on your behalf.

适用于 HTTPS 的解决方案

The Package Manager doesn’t provide an interactive terminal or dialog where you can enter your HTTP(S) username and password. To bypass this, use one of these workarounds:

Follow the instructions at Using private repositories with HTTPS Git URLs and Using passphrase-protected SSH keys with SSH Git URLs.
使用凭据管理器（Git Credential Manager for Windows 或 OSXKeyChain）。凭据管理器无需使用终端或命令提示符即可处理密码发送。
Use git-credentials from a terminal or command prompt, then launch the Hub from the same terminal so that Unity has access to the cached or stored credentials.
Use SSH to authenticate instead. If you set up your SSH key without a passphrase, the Package Manager doesn’t have to decrypt it to authenticate with the Git server. If you decide to use a passphrase for added security, you can use the ssh-agent on either macOS or Windows to get around the authentication problem.

适用于 SSH 的解决方案

If you use the SSH protocol to install a package by Git URL, you might get an authentication error from Git. This typically happens when you set up a private SSH key on your local computer that you protected with a passphrase.

此问题的解决方案是设置 SSH 代理，它可解锁您的 SSH 密钥以代表您向 Package Manager 进行身份验证。按照与您操作系统对应的部分中的说明进行操作：

设置 OpenSSH for Windows
将 SSH 密钥添加到适用于 macOS 的 SSH 代理

设置 OpenSSH for Windows

The built-in Windows OpenSSH version of the ssh-agent works better than the version available by default with Git for Windows. This procedure explains how to set up the OpenSSH client and add your key to its ssh-agent. If you are using Git for Windows, you can also prioritize the built-in Windows OpenSSH over the Git for Windows SSH agent:

Make sure the OpenSSH Client is installed. To do this, search for it in the Windows Settings Optional features window (Start > Settings, then search for “Optional features”). This applies to Windows 10+.
Check your %PATH% environment variable to make sure the built-in Windows OpenSSH location appears (for example, C:\WINDOWS\System32\OpenSSH\).

Note: If you’re already using Git for Windows, make sure the built-in Windows OpenSSH location appears before the Git for Windows SSH location in your %PATH% variable. This ensures that Windows uses the built-in Windows OpenSSH agent over the Git for Windows SSH agent.

在 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

Import your key into the ssh-agent. To do this, run ssh-add on the command line and then follow the instructions. By default, the agent adds the %USERPROFILE%\.ssh\id_rsa key and prompts you for the password.
```
# 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>
```
If you can’t remember the name of your key, use the following command to list your keys:
```
ssh-add -l
```
If you installed Git for Windows, reset the %GIT-SSH% environment variable to make sure that Git always uses the built-in Windows OpenSSH version of the ssh-agent:
```
[Environment]::SetEnvironmentVariable("GIT_SSH", "$((Get-Command ssh).Source)", [System.EnvironmentVariableTarget]::User)
```

将 SSH 密钥添加到适用于 macOS 的 SSH 代理

Use the ssh-add command to add your SSH keys to the ssh-agent running on your macOS system. The command parameter you use depends on your version of macOS:

On macOS 11 and earlier, use:

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

On macOS 12 and later, use:

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

运行此命令后，终端会要求输入密码以解锁您的 SSH 密钥，然后将它添加到 macOS 密钥链。但是，一旦您重新启动系统，存储在 ssh-agent 中的每个密钥都会重置。

To make sure you don’t need to re-enter your password after you restart your system, open the ~/.ssh/config file (or create one if you don’t find it), and add the following:

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

Restart your computer to apply these changes.

无法更新 Git 版本

If you’re trying to update your Git dependency to a newer version from the repository, but it’s not working, it’s probably because of a locked Git dependency. If you want to update your Git dependency to a newer version from the repository, use the Add package from Git URL button and enter a Git URL. For more information, refer to Locked Git dependencies.

‘Failed to parse http response’ in My Assets context

If you get the following message in the Console window when you try to download an Asset Store package, there might be a problem with your Asset Store cache:

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

To solve this problem, delete all downloaded assets from the Asset Store package directory and then try to download the assets again.

Warning: If your project has a lot of asset data, it might take a lot of time and bandwidth to re-download everything.

Package Manager 窗口中缺少“My Registries”

Not all registry providers are compatible with Unity’s Package Manager. If the package registry server you added doesn’t implement the /-/v1/search or /-/all endpoints, your scoped registry isn’t compatible with Unity’s Package Manager, and doesn’t appear under My Registries in the navigation panel of the Package Manager window.

缺失 MonoBehaviour 错误

在构建期间，如果有许多关于缺失行为的错误，则 UnityLinker 可能会错误地剥离它认为未引用的组件。它这样做的原因通常是剥离级别太激进。例如，如果 AssetBundle 中有一个预制件引用 2D SpriteShape 包中的 SpriteShape 组件，则对象可能会缺失并且可能会生成编译器警告。

To fix this, you can either lower the stripping level for the UnityLinker or declare the package’s assemblies inside the link.xml file to preserve them from being stripped:

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

For more information on stripping levels and the UnityLinker, refer to Managed code stripping.

本地文件夹或 tarball 路径

Diagnose network issues

手册

故障排除

Package Manager 窗口中的错误消息

System-wide issues

Package-specific issues

Package Manager 缺失或者窗口无法打开

将 Unity 升级到新版本后出现的问题

包安装失败

Unable to add package from Git URL

Insufficient drive space

Package version has no signature

Package version doesn’t have a valid signature

未找到“git”可执行文件

git-lfs：未找到命令

Repository not found

Could not read Username: terminal prompts disabled

适用于 HTTPS 的解决方案

适用于 SSH 的解决方案

设置 OpenSSH for Windows

将 SSH 密钥添加到适用于 macOS 的 SSH 代理

无法更新 Git 版本

‘Failed to parse http response’ in My Assets context

Package Manager 窗口中缺少“My Registries”

缺失 MonoBehaviour 错误