本地文件夹或 tarball 路径

诊断网络问题

故障排除

本节提供以下问题的信息

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

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

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

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

系统范围的问题

网络连接问题

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

网络错误消息
刷新资源出错（或刷新包出错）

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

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

已注销 Unity 帐户

单击列表面板内的登录按钮，通过 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”作为包版本。这是依赖项属性的已弃用值。如果您发现任何这样的行，请删除整行。包管理器仅安装在您的项目中作为依赖项明确包含的包，因此一旦您删除该条目，包管理器就会忽略该包并且不会安装它。

将 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，请转到存储库的页面，并从“克隆”按钮复制 URL。

Where to copy the URL on GitHub (A) and GitLab (B) — 在 GitHub (A) 和 GitLab (B) 上复制 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 使用一对公钥和私钥。您可以将您的公钥添加到Bitbucket、GitHub或GitLab，然后访问存储库，而无需输入用户名和密码。

但是，如果您已设置密码短语以保护您的 SSH 密钥安全，则仍需要在终端或对话框中输入该密码短语以授权您的密钥。在这种情况下，您可以使用 SSH 代理，它可以解锁您的 SSH 密钥以代表您对包管理器进行身份验证。

HTTPS 解决方案

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

按照使用 HTTPS Git URL 的私有存储库和使用带密码短语保护的 SSH 密钥的 SSH Git URL中的说明操作。
使用凭据管理器（Git Credential Manager for Windows或OSXKeyChain）。凭据管理器负责发送密码，而无需使用终端或命令提示符。
从终端或命令提示符使用git-credentials，然后从同一终端启动 Hub，以便 Unity 可以访问缓存或存储的凭据。
改用 SSH 进行身份验证。如果您在没有密码短语的情况下设置了 SSH 密钥，则包管理器无需对其进行解密即可对 Git 服务器进行身份验证。如果您决定使用密码短语以增强安全性，则可以在macOS或Windows上使用ssh-agent来解决身份验证问题。

SSH 解决方案

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

解决此问题的办法是设置 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 代理。

确保已安装 OpenSSH 客户端。为此，请在 Windows 设置的“可选功能”窗口中搜索它（开始>设置，然后搜索“可选功能”）。这适用于 Windows 10 及更高版本。
检查您的%PATH%环境变量，以确保内置的 Windows OpenSSH 位置出现（例如，C:\WINDOWS\System32\OpenSSH\）。

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

在 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

将您的密钥导入 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
```
如果您安装了 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 URL 引用而不是版本，并且无法保证包的质量、稳定性、有效性，甚至其package.json文件中声明的版本是否符合关于此包的正式发布版本的语义版本控制规则。更多信息
请参阅术语表更新到较新版本，但它不起作用，这可能是由于锁定的 Git 依赖项导致的。如果您想将您的 Git 依赖项更新到存储库中的较新版本，请使用从 Git URL 添加包按钮并输入 Git URL。有关更多信息，请参阅锁定的 Git 依赖项。

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

如果您在尝试从 Asset Store 下载资源包时在控制台窗口中收到以下消息，则您的资源包缓存可能存在问题。

[PackageManager] 错误无法解析响应。UnityEditor.AsyncHTTPClient![:D](https://forum.unity.com/styles/default/xenforo/clear.png)one(State, Int32)

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

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

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

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

缺少 MonoBehaviour 错误

在构建过程中，如果出现大量有关缺少行为的错误，则 UnityLinker 可能错误地剥离了它认为未引用的组件。它通常会这样做，因为剥离级别过于激进。例如，如果您在 AssetBundle 中有一个预制件一种资产类型，允许您存储一个完整的 GameObject，包括组件和属性。预制件充当模板，您可以从中在场景中创建新的对象实例。更多信息
请参阅术语表，它引用了 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 的更多信息，请参阅托管代码剥离。

本地文件夹或 tarball 路径

诊断网络问题

Unity 手册

故障排除

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

系统范围的问题

特定于包的问题

包管理器丢失或窗口无法打开

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

包安装失败

无法从 Git URL 添加包

磁盘空间不足

包版本没有签名

包版本没有有效的签名

未找到“git”可执行文件

git-lfs：找不到命令

未找到存储库

无法读取用户名：终端提示已禁用

HTTPS 解决方案

SSH 解决方案

为 Windows 设置 OpenSSH

将 SSH 密钥添加到 macOS 的 SSH 代理

无法更新 Git 版本

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

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

缺少 MonoBehaviour 错误