故障排除

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

• Package Manager 窗口中的错误消息
• Missing MonoBehaviour errors
• Package Manager 缺失或者窗口无法打开
• 将 Unity 升级到新版本后出现的问题
• 包安装失败
• 无法识别包
• Windows 上加载 hostfxr.dll 时出错
• 重置项目的包配置
• Git URL 的身份验证问题

如果遇到与网络有关的问题，也可以运行 Unity Package Manager Diagnostics 工具。有关更多信息，请参阅网络问题。

Package Manager 窗口中的错误消息

在 Package Manager 遇到问题时，Package Manager 窗口中会显示错误指示符：

• 系统范围的问题

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

  

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

  If your network connection is working, but you are not signed into your Unity account, the Package Manager doesn’t display any Asset Store packages. When you try to use the My Assets scope, the Package Manager displays an error in the status bar:

  

  在列表视图中单击 Sign in 按钮可通过 Unity Hub 登录到您的 Unity 帐户。

• 包特有的问题

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

  

缺失 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 的更多信息，请参阅托管代码剥离。

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

如果您的 package.manifest 文件有格式错误，则在 Unity 控制台中将出现类似以下错误：

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

You can use the information contained in the error message to fix the JSON. There are a number of online validators that you can use to try to correct the problem. Once you save the corrected file, Unity reloads the Package Manager window.

As of 2019.3, your manifest.json file should not contain any references to the com.unity.package-manager-ui package. You can either reset your project’s package configuration or remove the following line from the manifest’s dependencies list:

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

If you are still experiencing problems, check to see 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.

如果 Package Manager 仍然无法加载，请遵循无法识别包和重置项目的包配置下的步骤进行操作。

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

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

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

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

• 备份项目下的 Packages 文件夹，然后再删除该文件夹。
• 备份项目的 Packages 文件夹中的包来源文件，然后将它们删除，只留下 manifest.json 文件。然后尝试重新加载项目。
• 创建一个新的空项目。如果 Package Manager 窗口加载成功，请将失败项目中的 Library/PackageCache/com.unity.package-manager-ui@<version> 文件夹替换为新创建的项目中的同一个文件夹。
• 作为最后的选择，您可以重置项目（重置为默认的包配置），然后将包逐个添加回来，直到问题得到解决为止。

包安装失败

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

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

• Windows：C:\Users\yourname\AppData\Local\Unity\cache
• MacOS：~/Users/Library/Unity/cache

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

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

无法识别包

如果看到很多编译错误，可能表明 Unity 无法识别现有项目中的包。在这种情况下，可能缺少 .NET 组件。

对于 Windows：

1. 下载并安装 Visual Studio 2017 版本 15.9.0 或更高版本，并在 Other Toolsets 下面选中 .NET Core cross-platform development workload。
2. 下载并安装 .NET SDK v2.2.101 组件。

对于 MacOS：

1. 下载并安装 .NET SDK v2.2.101 组件。

2. 在 Visual Studio 中安装所有建议的更新

3. 使用 homebrew 来计划和安装 mono：

     brew update
       brew install mono # optional
       brew upgrade mono
   

4. 如有必要，删除项目下的 Library/obj/temp 文件夹，然后重新启动 Unity。

5. 如果仍然遇到困难，请尝试重新启动计算机。

Windows 上加载 hostfxr.dll 时出错

如果控制台报告说找到了 hostfxr.dll 库，但 Unity 无法从 C:\<path_to_app>\hostfxr.dll 加载该库，那么可以通过安装 KB2999226 和 KB2533623 补丁在 Windows 7 或 Windows Server 2008 R2 上修正此错误。

重置项目的包配置

如果一个项目有太多的包问题，则可以将项目重置为 Unity 的 Editor 版本的默认包配置。此操作将重置项目中的所有包。这可能无法解决问题的根源，但是可以帮助您找出问题所在。

注意：您无法撤消对包配置的重置操作，因此请确保首先备份 manifest.json 文件，或者确保您的项目处于源代码控制之下。此外，还可以采取其他预防措施，包括：克隆项目，在克隆版本上测试操作之后再继续。

要恢复为默认包配置，请从 Help 菜单中选择 Reset Packages to defaults。

重置项目的克隆版本

在执行最终更改之前，您也可以测试是否可以恢复为默认包：

1. 要克隆项目，请复制粘贴项目文件夹，然后重命名项目文件夹以便于识别（例如，如果您的项目名为 MyProject，则可以使用类似 clone_MyProject 的名称）。

2. 加载新克隆的项目。

3. 从 Help 菜单中，选择 Reset Packages to defaults。

   根据项目的大小，这可能需要几分钟。

4. 检查是否成功重置了包。如果成功，则表示您可以安全地对原始项目执行操作。

Git URL 的身份验证问题

如果使用 SSH 协议通过 Git URL 来安装包，即使您正在后台运行 ssh-agent 并且您的 PID 环境变量已正确设置，也可能会遇到来自 Git 的身份验证错误。

尽管您的脚本可以在后台成功启动 ssh-agent，但是导出的环境变量仅适用于运行脚本的 Bash shell 以及之后由该脚本启动的任何子进程。这是因为您的脚本无法更改父进程、无关进程或先前创建的子进程中的环境变量。即使脚本位于 .bashrc 中，也只会在 Bash shell 中执行。

通过双击 Unity 图标或使用 Hub 启动 Unity 或 Unity Hub（在 Windows 和 macOS 中）时，不会在 shell 中运行，因此不会执行脚本。这意味着 Unity Editor 进程不会设置这些变量，因此 Unity 调用的 Git 进程最终也不会设置这些变量。

要解决此问题，可以执行以下操作之一：

• Open a Bash shell first (before opening the Hub) and manually launch the Unity Editor from that shell.
• 如果您使用的是 Windows，则可以使用 setx 命令在 Hub 进程启动之前在 Windows 注册表中永久设置环境变量。如果您可以确保脚本在启动时运行一次，并且 Hub 不会与 Windows 一起启动，则此解决方案最有效。例如：

  # Expose env variables to native windows
    setx SSH_AGENT_PID "$SSH_AGENT_PID"
    setx SSH_AUTH_SOCK "$SSH_AUTH_SOCK"