# 故障排除

> Get information for troubleshooting Package Manager issues.

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

| **错误类型：**            | **错误消息：**                                                                                                                                           |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| 一般启动问题               | - [Package Manager 窗口中的错误消息](#Errors)- [Package Manager 缺失或者窗口无法打开](#Missing)- [将 Unity 升级到新版本后出现的问题](#Upgrade)                                     |
| 包安装问题                | - [包安装失败](#Failed)- [无法从 Git URL 添加包](#git-url-pkg)- [驱动器空间不足](#drive-space)                                                                        |
| 包签名问题                | - [包版本没有签名](#pkg-no-sig)- [包版本没有有效的签名](#pkg-invalid-sig)                                                                                            |
| 安装 git 依赖关系时的问题      | - [未找到“git”可执行文件](#git-not-found)- [git-lfs：未找到命令](#git-lfs)- [找不到代码仓库](#bad-url)- [无法读取用户名：终端提示被禁用](#prompts-disabled)- [无法更新 Git 版本](#locked-git) |
| 资源商店的资源包 (My Assets) | - [My Assets 上下文中出现“无法解析 http 响应”](#failed-http-response)                                                                                           |
| 作用域注册表               | - [Package Manager 窗口中缺少“My Registries”](#scoped-missing)                                                                                           |
| 构建包时的问题              | - [缺失 MonoBehaviour 错误](#Linker)                                                                                                                    |

如果遇到与网络有关的问题，也可以运行 Unity Package Manager **Diagnostics** 工具。有关更多信息，请参阅[诊断网络问题](/engine/6000.0/manual/packages-list/packages/upm-errors/upm-network.md)。

## Package Manager 窗口中的错误消息

在 Package Manager 遇到问题时，[Package Manager 窗口](/engine/6000.0/manual/packages-list/packages/upm-ui.md)中会显示错误指示符：

### 系统作用域的问题

* **网络连接类型**

  当 Package Manager 检测到与特定包无关的问题时，[状态栏](/engine/6000.0/manual/packages-list/packages/upm-ui.md#StatusBar)中会显示错误消息。例如，如果 Package Manager 无法访问[包注册表服务器](/engine/6000.0/manual/packages-list/packages/upm-concepts.md#Registry)，则将在状态栏中显示以下消息：


  **网络错误消息:**
  ![](/api/media?file=/engine/6000.0/media/images/upm-ui-errors.png)

* **刷新资源时出错（或刷新资源包时出错）**

  如果您的网络无法访问包注册表服务器，可能是因为网络存在连接问题。您或系统管理员[诊断和修复网络错误](/engine/6000.0/manual/packages-list/packages/upm-errors/upm-network.md)后，状态栏将清空。

  如果您的网络连接正常，但尚未登录 [Unity 帐户](https://id.unity.com/)，那么 Package Manager 将不会显示任何来自资源商店的资源包。尝试使用 **My Assets** 上下文时，Package Manager 会提示您登录：


  **从 Unity 帐户登出:**
  ![](/api/media?file=/engine/6000.0/media/images/upm-ui-unityid.png)

  在[列表面板](/engine/6000.0/manual/packages-list/packages/upm-ui/list.md)中单击**登录 (Sign in)** 按钮可通过 [Unity Hub](https://docs.unity3d.com/hub/manual/index.html) 登录到您的 Unity 帐户。

### 包特有的问题

* 如果特定的包在加载或安装时（例如，在确定要加载的包版本时）出现问题，则损坏的包旁边的[列表面板](/engine/6000.0/manual/packages-list/packages/upm-ui/list.md)中将显示错误图标 () **(A)**。要找出问题所在，请核查损坏的包的[详细信息面板](/engine/6000.0/manual/packages-list/packages/upm-ui/details.md)以查看详细的错误消息 **(B)**：


  **依赖关系错误消息:**
  ![](/api/media?file=/engine/6000.0/media/images/upm-ui-errormsg.png)

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

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

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

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

此错误消息表示 `manifest.json` 文件格式错误。它还告诉您 Package Manager 无法解析文件的行号，以便可以修复 JSON。您可以使用多个在线验证器来更正问题。保存更正的文件后，Unity 将重新加载 Package Manager 窗口。

如果您从更早版本的 Unity 编辑器升级，则包清单文件可能存在其他问题：

* 从 2019.3 开始，您的 `manifest.json` 文件不应包含对 **com.unity.package-manager-ui** 包的任何引用。从清单的依赖项列表中删除以下行：

  ```lang-json
      "com.unity.package-manager-ui": "2.1.1",
  ```

* 检查项目清单是否使用\*\*“xclude“\*\*作为包版本。这是[依赖性](/engine/6000.0/manual/packages-list/packages/upm-manifest-prj.md#dependencies)属性的过时值。如果找到类似这些的行，请删除整行。Package Manager 仅安装在项目中作为依赖项显式包含的包，因此，一旦删除该条目，Package Manager 将忽略并且不会安装该包。

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

当您将项目升级到更高的 Unity 版本时，Package Manager 会自动将不兼容的包更新为更高的兼容版本。但是，如果您的包不能编译，则 Package Manager 会在**控制台 (Console)** 窗口中显示错误消息。

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

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

* 备份项目下的 `Packages` 文件夹，然后再删除该文件夹。
* 备份项目的 `Packages` 文件夹中的包来源文件，然后将它们删除，只留下 `manifest.json` 文件。然后尝试重新加载项目。
* 创建一个新的空项目。如果 Package Manager 窗口加载无误，请将失败项目中的 `Library/PackageCache/com.unity.package-manager-ui` 文件夹替换为新创建的项目的同一文件夹。

## 包安装失败

如果您尝试从注册表安装新的包但无法安装，可能是由于权限问题所致。

必须对[缓存文件夹](/engine/6000.0/manual/packages-list/packages/upm-concepts/upm-cache.md)具有完整权限：

* Windows（用户帐户）：`%LOCALAPPDATA%\Unity\cache\upm`
* Windows（系统用户）：`%ALLUSERSPROFILE%\Unity\cache\upm`
* macOS：`$HOME/Library/Caches/Unity/upm`
* Linux：`$HOME/.cache/Unity/upm`

可能是网络存在问题。检查[防火墙](/engine/6000.0/manual/packages-list/packages/upm-config/network.md#Firewall)和[代理](/engine/6000.0/manual/packages-list/packages/upm-config/network.md#Proxy)设置。

有时，学校、政府机关或受网络保护的工作场所等机构环境会设置代理服务器来控制网络与互联网之间的通信，并使用自己的服务器证书，而 Unity 或 Package Manager 无法识别这些证书。请与您的网络管理员联系。

## 无法从 Git URL 添加包

请参阅[找不到代码仓库](#bad-url)。

## 驱动器空间不足

如果您的安装驱动器空间不足或空间不足，请考虑以下解决方案：

* 更改全局缓存的位置。请参阅[自定义全局缓存](/engine/6000.0/manual/packages-list/packages/upm-config/cache.md)。
* 更改资源包缓存的位置。请参阅自[定义资源包缓存位置](/engine/6000.0/manual/packages-list/packages/upm-config/cache-as.md)。
* 减小注册表数据缓存限制的最大大小。请参阅[自定义全局缓存](/engine/6000.0/manual/packages-list/packages/upm-config/cache.md)。

## 包版本没有签名

从作用域注册表获取 Unity 包时，可能会出现此消息。Unity 会对其创建的包进行签名，但较旧的包除外，这些包不一定会在后续版本中重新签名。如果将未签名的 Unity 包从作用域注册表复制到另一个注册表，Package Manager 无法确定包内容是否安全，以及是否与原始包一致。

如果收到此消息，请尝试以下解决方案：

* 使用包的另一个版本。
* 从 Unity Registry 获取 Unity 包。
* 如果您拥有作用域注册表，请确保从 Unity Registry 复制包的最新版本。

## 包版本没有有效的签名

包具有签名，可确保内容在传输之前或传输过程中未更改。无效签名通常发生在以下情况：

* 有人在自己的注册表上发布了经过修改的包。
* 将文件传输到终端用户时发生错误。

在上述两种情况下，Package Manager 会认为该包可能有恶意风险。

当遇到签名无效时，可以尝试安装该包的其他版本。此外，应避免使用 Unity Registry 以外的注册表中的 Unity 包。

如果要共享一个已修复问题的 Unity 包，请考虑使用 Git URL 或将包嵌入到项目中。

## 未找到“git”可执行文件

如果尝试从 git URL 安装包，则会出现与此类似的消息：

```lang-shell
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（大型文件存储）的包，则可能会收到以下错误消息：

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

这表明您的计算机上可能未安装 Git LFS。若要确保安装，请在命令行上进行测试：

```lang-shell
git lfs --version
```

如果命令返回如下类似内容，则会安装 Git LFS：

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

否则，您可以按照 [Bitbucket](https://www.atlassian.com/git/tutorials/git-lfs) [GitHub](https://git-lfs.github.com/) 说明进行安装。

## Repository not found

如果 Package Manager 找不到您指定的代码仓库，[Unity 控制台](/engine/6000.0/manual/unity-editor/using-the-editor/console.md)将显示错误消息：

```
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 复制到的位置:**
![](/api/media?file=/engine/6000.0/media/images/upm-giturl-locate.png)

单击 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) 的条目。Package Manager 进程需要在 `PATH` 变量中输入这些条目。

## 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)
```

通常，出现此消息是由于：Package Manager 没有提供用来输入 HTTP 的用户名和密码或者输入口令短语来解锁 SSH 密钥的交互式终端或对话框。

* 如果使用 **HTTP(S)**，每次登录 Bitbucket、GitHub 或 GitLab 时，都需要在终端或对话框中输入用户名和密码。但是，Package Manager 没有提供用来输入 HTTP(S) 的用户名和密码的交互式终端或对话框。

  若要绕过此问题，请使用[适用于的 HTTPS 解决方案](#https-auth)中建议的解决方法之一。

* **SSH** 使用一对公有和私有 SSH 密钥。您可以将公共 SSH 密钥添加到 [Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/set-up-an-ssh-key/)、[GitHub](https://help.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh) 或 [GitLab](https://gitlab.com/help/ssh/README.md) 中，然后无需输入用户名和密码即可访问代码仓库。

  但是，如果您设置了一个口令短语来保护 SSH 密钥的安全，则仍然需要在终端或对话框中输入该口令短语以便授权密钥。在这种情况下，可以[使用 SSH 代理](#ssh-add)，它可解锁您的 SSH 密钥以代表您向 Package Manager 进行身份验证。

### 适用于 HTTPS 的解决方案

Package Manager 没有提供用来输入 HTTP(S) 用户名和密码的交互式终端或对话框。要绕过这一点，请使用下列其中一种变通方法：

* 请遵循[通过 HTTPS Git URL 访问私有代码仓库](/engine/6000.0/manual/packages-list/packages/upm-config/https-git.md)和[配合使用受口令短语保护的 SSH 密钥与 SSH Git URL](/engine/6000.0/manual/packages-list/packages/upm-config/ssh-git.md) 中的说明。
* 使用凭据管理器（[Git Credential Manager for Windows](https://github.com/Microsoft/Git-Credential-Manager-for-Windows) 或 [OSXKeyChain](https://support.apple.com/en-ca/guide/keychain-access/welcome/mac)）。凭据管理器无需使用终端或命令提示符即可处理密码发送。
* 从终端或命令提示符窗口中使用 [git-credentials](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage)，然后，从同一终端启动 Hub，以便 Unity 可以访问缓存或存储的凭证。
* 请改用 SSH 进行身份验证。如果您在没有口令短语的情况下设置 SSH 密钥，则 Package Manager 无需将其解密即可向 Git 服务器进行身份验证。如果您决定使用口令短语增加安全性，可以在 [macOS](#ssh-agent-macos) 或 [Windows](#openssh-win)上使用 **ssh-agent** 应对身份验证问题。

### 适用于 SSH 的解决方案

如果您使用 SSH 协议[通过 Git URL 安装包](/engine/6000.0/manual/packages-list/packages/upm-manifest-prj/upm-git.md#Git-SSH)，则可能会从 Git 收到身份验证错误。当您在受口令短语保护的本地计算机上设置私有 SSH 密钥时，通常会发生这种情况。

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

* [设置 OpenSSH for Windows](#openssh-win)
* [将 SSH 密钥添加到适用于 macOS 的 SSH 代理](#ssh-agent-macos)

#### 设置 OpenSSH for Windows

内置 Windows OpenSSH 版本的 **ssh-agent** 比 Git for Windows 默认提供的版本效果更好。此过程说明如何设置 OpenSSH 客户端并将密钥添加到其 ssh-agent。如果使用 Git for Windows，则还可以使内置 Windows OpenSSH 优先于 Git for Windows SSH 代理：

1. 确保安装了 OpenSSH 客户端。为此，请在 Windows 的设置**可选功能**窗口中搜索该功能（**开始 (Start)** > **设置 (Settings)**，然后搜索“可选功能”）。这适用于 Windows 10+。

2. 检查 `%PATH%` 环境变量以确保显示内置 Windows OpenSSH 位置（例如，`C:\WINDOWS\System32\OpenSSH\`）。

   **注意**：如果已在使用 Git for Windows，请确保在 `%PATH%` 变量中，内置 Windows OpenSSH 位置出现在 Git for Windows SSH 位置之前。这可确保 Windows 使用内置 Windows OpenSSH 代理而不是 Git for Windows SSH 代理。

3. 在 PowerShell 终端中，启动 `ssh-agent` 进程并确保它自动启动：

   ```lang-powershell
   # 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` 密钥并提示您输入密码。

   ```lang-powershell
   # Import the key
   ssh-add
   ```

   若要使用不同的密钥，可以将它指定为参数：

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

   如果不记得密钥的名称，请使用以下命令来列出密钥：

   ```lang-powershell
   ssh-add -l
   ```

5. 如果您安装了 Git for Windows，请重置 `%GIT-SSH%` 环境变量以确保 Git 始终使用内置 Windows OpenSSH 版本的 ssh-agent：

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

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

使用 `ssh-add` 命令可将 SSH 密钥添加到在 macOS 系统上运行的 [ssh-agent](https://www.ssh.com/ssh/agent)。使用的命令参数取决于 macOS 版本：

* 在 macOS 11 及更早版本上，使用：

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

* 在 macOS 12 或更高版本上，使用：

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

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

若要防止在重新启动系统后重新输入密码，请打开 `~/.ssh/config` 文件（如果找不到，则创建一个），并添加以下内容：

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

重新启动计算机以应用这些更改。

## 无法更新 Git 版本

如果您尝试从代码仓库将 Git 依赖关系更新到较新版本，但它不起作用，则可能是因为 Git 依赖关系[已锁定](/engine/6000.0/manual/packages-list/packages/upm-conflicts/auto.md)。如果要从代码仓库将 Git 依赖关系更新到较新版本，请使用[从 Git URL 添加包 (Add package from git URL)](/engine/6000.0/manual/packages-list/packages/upm-ui/actions/giturl.md) 按钮并输入 Git URL。有关更多信息，请参阅[已锁定的 Git 依赖关系](/engine/6000.0/manual/packages-list/packages/upm-manifest-prj/upm-git.md#git-locks)。

## My Assets 上下文中出现“无法解析 Http 响应”

当您尝试从资源商店下载资源包时，如果在**控制台**窗口中收到以下消息，那么您的资源包缓存可能存在问题：

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

要解决此问题，请从[下载资源包文件的位置](/engine/6000.0/manual/working-in-unity/assets-and-media/asset-store/packages.md#asset-location)删除所有下载的资源，然后尝试再次下载资源。

**警告**：如果您的项目包含大量资源数据，重新下载所有内容可能需要大量时间和带宽。

## Package Manager 窗口中缺少“My Registries”

并非所有注册表提供程序都与 Unity 的 Package Manager 兼容。如果添加的包注册表服务器未实现 `/-/v1/search` 或 `/-/all` 终端，则[作用域注册表](/engine/6000.0/manual/packages-list/packages/upm-scoped.md)与 Unity 的 Package Manager 不兼容，不会出现在 Package Manager 窗口的[导航面板](/engine/6000.0/manual/packages-list/packages/upm-ui/nav.md)中 **My Registries** 上下文中。

## 缺失 MonoBehaviour 错误

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

若要解决此问题，可以降低 UnityLinker 的剥离级别或是在 `link.xml` 文件内声明包的程序集以防止这些程序集遭到剥离：

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

有关剥离级别和 UnityLinker 的更多信息，请参阅[托管代码剥离](/engine/6000.0/manual/scripting/compilation-and-code-reload/backends/managed-code-stripping.md)。