包管理器故障排除

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

错误类型：	错误信息：
一般启动问题	- 包管理器窗口 中的错误消息 - 包管理器丢失或窗口未打开 - 将 Unity 升级到新版本后出现问题
包安装问题	- 包安装失败 - 无法从 Git URL 添加包 - 驱动器空间不足
包签名问题	- Unity 无法验证此包，因为它缺少签名 - 包版本没有有效的签名
安装 git 依赖项时出现问题	- 未找到 “git”可执行文件 - git-lfs：未找到 命令 - 找不到存储库 - 无法读取用户名：终端提示已禁用 - 无法更新 Git 版本
资产包来自 Unity 项目或项目元素的文件和数据的集合，这些文件和数据被压缩并存储在一个文件中，类似于 Zip 文件，使用.unitypackage外延。 资源包是共享和重用 Unity 项目和资源集合的便捷方式。更多信息 请参阅术语表从Asset Store由 Unity 和社区成员创建的不断增长的免费和商业资产库。提供各种各样的资产，从纹理、模型和动画到整个项目示例、教程和编辑器扩展。更多信息 请参阅术语表（我的资产）	- “我的资产”上下文中的“无法解析 http 响应”
作用域注册表	- 包管理器窗口中缺少“我的注册表”
构建包时的问题	- 缺少 MonoBehaviour 错误

如果遇到可能与网络相关的问题，还可以运行 Unity 包管理器诊断工具。有关详细信息，请参阅诊断网络问题。

“包管理器”窗口中的错误消息

当包管理器遇到问题时，它会在包管理器窗口中显示错误指示器。

系统范围的问题

• 网络连接问题

  当包管理器检测到与特定包无关的问题时，错误消息将显示在状态栏中。例如，如果包管理器无法访问包注册表服务器，则会在状态栏中显示以下消息：

  

• 刷新资产时出错（或刷新包时出错）

  如果网络无法访问包注册表服务器，可能是因为网络存在连接问题。当您或您的系统管理员诊断并修复网络错误时，状态栏将清除。

  如果您的网络连接正常，但您尚未登录 Unity 帐户，则包管理器不会显示任何 Asset Store 包。当您尝试使用 My Assets 上下文时，包管理器会提示您登录：

  

  单击列表面板中的“登录”按钮，通过 Unity Hub 登录您的 Unity 帐户。

特定于包的问题

• 如果特定包在加载或安装时出现问题（例如，在确定要加载的包版本时），则错误图标 （） 将出现在受损包 （A） 旁边的列表面板中。要找出问题所在，请检查受损包的详细信息面板以查看详细的错误消息 （B）：

  

缺少包管理器或窗口无法打开

包管理器窗口可能会被移出屏幕或被另一个窗口隐藏。发生这种情况时，包管理器窗口看起来无法打开。在这种情况下，您可以尝试重置窗口布局（窗口>布局>默认）并重新打开包管理器窗口。

如果“包管理器”窗口仍未出现，请检查您的 Unity控制台窗口一个 Unity 编辑器窗口，显示 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",
  

• 检查您的项目清单每个 Unity 项目都有一个项目清单，用作包管理器的入口点。此文件必须在<project>/Packages目录。包管理器使用它来配置许多内容，包括该项目的依赖项列表，以及要查询包的任何包存储库。更多信息
  请参阅术语表使用“exclude”作为包版本。这是 dependencies 属性的过时值。如果您发现任何类似的线条，请删除整条线。包管理器仅安装显式包含在项目中作为依赖项包含的包，因此一旦删除该条目，包管理器将忽略该包并且不会安装它。

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

将项目升级到较新的 Unity 版本时，包管理器会自动将不兼容的包更新为较新的兼容版本。但是，如果包未编译，包管理器会在控制台窗口中显示错误消息。

要更正这些消息，请阅读错误消息并解决任何问题。例如，一个包可能缺少对另一个包或版本的依赖项。在这种情况下，您可以尝试自己安装软件包。

您还可以尝试以下一系列解决方案，直到找到有效的解决方案：

• 备份然后删除Packages文件夹。
• 备份并删除项目Packages文件夹，只留下manifest.json文件。然后尝试重新加载项目。

包安装失败

如果您尝试从注册表安装新包但它不起作用，可能是由于权限问题造成的。

您必须对缓存文件夹具有完全权限：

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

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

有时，学校、政府办公室或受网络保护的工作场所等机构环境会设置代理服务器来控制网络和 Internet 之间的流量，并使用自己的服务器证书，这些证书无法被 Unity 或包管理器识别。请与您的网络管理员联系。

无法从 Git URL 添加包

请参阅未找到存储库。

驱动器空间不足

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

• 更改全局缓存的位置。请参阅自定义全局缓存。
• 更改资产包缓存的位置。请参阅自定义资产包缓存位置。
• 减小注册表数据缓存限制的最大大小。请参阅自定义全局缓存。

Unity 无法验证此包，因为它缺少签名

从 Unity 6.3 开始，包管理器会检查每个包中的签名。包签名使开发人员和用户更容易确认包的来源和完整性，并检测分发过程中任何未经授权的更改或篡改。

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

• 使用包的签名版本。如果找不到，请联系包所有者并询问他们是否可以发布签名版本。
• 如果你拥有该包，请参考以发布者身份对包进行签名。

包版本没有有效的签名

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

• 有人在自己的注册表上发布了修改的包。
• 将文件传输给最终用户时发生错误。

在这两种情况下，包管理器都会将包视为潜在的恶意包。

当您收到无效的签名时，您可以尝试安装其他版本的包。此外，避免使用 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，请转到存储库的页面并从“克隆”按钮复制 URL：

单击 GitHub （A） 或 GitLab （B） 上 URL 右侧的按钮，将 URL 复制到剪贴板。

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

• 如果您针对特定修订版，请确保您的修订版排在最后。 例如：
  https://github.example.com/myuser/myrepository1.git#revision
• 如果您以修订版本为目标，并且该包不在根目录下，请确保pathquery 参数位于修订锚点之前。 例如：
  https://github.example.com/myuser/myrepository.git?path=/example/folder#v1.2.3

如果存储库和 URL 的位置正确，请检查您的PATH系统环境变量。确保PATH变量包含 Git 的条目cmd目录 （Windows） 和 Gitbin目录（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 代理代表您向包管理器进行身份验证。

HTTPS 解决方案

包管理器不提供交互式终端或对话框，您可以在其中输入 HTTP（S） 用户名和密码。要绕过此问题，请使用以下解决方法之一：

• 请按照将私有存储库与 HTTPS Git URL 配合使用和将受密码保护的 SSH 密钥与 SSH Git URL 配合使用中的说明进行作。
• 使用凭据管理器（适用于 Windows 的 Git 凭据管理器或 OSXKeyChain）。凭据管理器无需使用终端或命令提示符即可处理发送密码。
• 从终端或命令提示符使用 git-credentials，然后从同一终端启动 Hub，以便 Unity 可以访问缓存或存储的凭据。
• 请改用 SSH 进行身份验证。如果您在没有密码的情况下设置 SSH 密钥，则包管理器无需解密它即可向 Git 服务器进行身份验证。如果您决定使用密码来提高安全性，则可以在 macOS 或 Windows 上使用 ssh-agent 来解决身份验证问题。

SSH 解决方案

如果使用 SSH 协议通过 Git URL 安装包，则可能会收到来自 Git 的身份验证错误。当您在本地计算机上设置使用密码保护的私有 SSH 密钥时，通常会发生这种情况。

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

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

为 Windows 设置 OpenSSH

ssh-agent 的内置 Windows OpenSSH 版本比 Git for Windows 默认提供的版本效果更好。此过程介绍如何设置 OpenSSH 客户端并将密钥添加到其 ssh-agent。如果您使用的是 Git for Windows，您还可以优先考虑内置的 Windows OpenSSH 而不是 Git for Windows SSH 代理：

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

2. 检查您的%PATH%环境变量来确保显示内置的 Windows OpenSSH 位置（例如，C:\WINDOWS\System32\OpenSSH\).

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

3. 在 PowerShell 终端中，启动ssh-agentprocess 并确保它自动启动：

   # 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. 如果您安装了 Git for Windows，请重置%GIT-SSH%环境变量来确保 Git 始终使用内置的 Windows OpenSSH 版本的 ssh-agent：

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

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

使用ssh-add命令将您的 SSH 密钥添加到 macOS 系统上运行的 ssh-agent。您使用的命令参数取决于您的 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 依赖项，而不是从包注册表中检索 Git 依赖项。Git 依赖项使用 Git URL 引用而不是版本，并且无法保证包的质量、稳定性、有效性，甚至无法保证其package.json文件遵循有关此包的正式发布版本的语义版本控制规则。更多信息
请参阅术语表到存储库中的较新版本，但它不起作用，可能是因为锁定了 Git 依赖项。如果要将 Git 依赖项从存储库更新到较新版本，请使用“从 Git URL 添加包”按钮并输入 Git URL。有关更多信息，请参阅锁定的 Git 依赖项。

“我的资产”上下文中的“无法解析 http 响应”

如果你在尝试从资产商店下载资产包时，在控制台窗口中收到以下消息，则你的资产包缓存可能存在问题：

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

要解决此问题，请从“下载的资产包文件的位置”中删除所有已下载的资产，然后再次尝试下载资产。

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

包管理器窗口中缺少“我的注册表”

并非所有注册表提供程序都与 Unity 的包管理器兼容。如果您添加的包注册表服务器未实现/-/v1/search或/-/allendpoints，则作用域注册表与 Unity 的包管理器不兼容，并且不会显示在包管理器窗口导航面板中的“我的注册表”下。

缺少 MonoBehaviour 错误

在构建时，如果存在大量关于 Missing Behavior 的错误，则 UnityLinker 可能会错误地剥离它认为未引用的组件。它经常这样做是因为剥离水平过于激进。例如，如果您有预制件：一种资产类型，允许您存储包含组件和属性的游戏对象。预制件充当模板，你可以从中在场景中创建新的对象实例。更多信息
请参阅术语表在引用 2D SpriteShape 包中的 SpriteShape 组件的 AssetBundle 中，该对象可能丢失，并可能生成编译器警告。

要解决此问题，您可以降低 UnityLinker 的剥离级别，或者在link.xml文件以保护它们不被剥离：

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

有关剥离级别和 UnityLinker 的详细信息，请参阅托管代码剥离。

其他资源

• 诊断网络问题