本节提供有关以下问题的信息:
错误类型: | 错误消息: |
---|---|
一般启动问题 | - Package Manager 窗口中的错误消息 - Package Manager 缺失或窗口无法打开 - 将 Unity 升级到新版本后出现的问题 - 重置项目的包配置 |
包安装问题 | - 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) | - My Assets 上下文中出现“无法解析 Http 响应” |
范围注册表 | - 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, see Diagnose network issues.
The Package Manager displays error indicators in the Package Manager window when it encounters problems.
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:
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 displays an error in the status bar:
Click the Sign in button inside the list view to sign into your Unity account through the Unity Hub.
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 package list next to the compromised package (A). To find out what the problem is, open the compromised package’s details view to see the detailed error message (B):
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
}
此错误消息表明 manifest.json
文件格式错误。它还告诉您 Package Manager 无法解析文件的行号,以便可以修复 JSON。您可以使用许多在线验证器来更正问题。保存更正的文件后,Unity 将重新加载 Package Manager 窗口。
如果您从早期版本的 Unity 编辑器升级,则包清单文件可能存在其他问题:
从 2019.3 开始,您的 manifest.json
文件不应包含对 com.unity.package-manager-ui 包的任何引用。可重置项目的包配置或从清单的依赖关系列表中删除以下行:
"com.unity.package-manager-ui": "2.1.1",
检查项目清单是否使用 “exclude” 作为包版本。这是 dependencies 属性的过时值。如果找到类似这些的行,请删除整行。Package Manager 仅安装在项目中作为依赖项显式包含的包,因此,一旦删除该条目,Package Manager 将忽略并且不会安装该包。
If the Package Manager still fails to load, follow the procedure under Resetting your project’s package configuration.
当您将项目升级到更高的 Unity 版本时,Package Manager 会自动将不兼容的包更新为更高的兼容版本。但是,如果您的包不能编译,则 Package Manager 会在控制台中显示错误消息。
要处理这些消息,请阅读错误消息并尽可能解决所有问题。例如,一个包可能缺少对另一个包或版本的依赖。在这种情况下,您可以尝试自己安装该包。
您也可以按照以下顺序来尝试每个解决方案,直到找到可行的解决方案:
Packages
文件夹,然后再删除该文件夹。Packages
文件夹中的包来源文件,然后将它们删除,只留下 manifest.json
文件。然后尝试重新加载项目。Library/PackageCache/com.unity.package-manager-ui@<version>
文件夹替换为新创建的项目中的同一个文件夹。
如果一个项目有太多的包问题,则可以将项目重置为 Unity 的 Editor 版本的默认包配置。此操作将重置项目中的所有包。这可能无法解决问题的根源,但是可以帮助您找出问题所在。
注意:您无法撤消对包配置的重置操作,因此请确保首先备份 manifest.json
文件,或者确保您的项目处于源代码控制之下。此外,还可以采取其他预防措施,包括:克隆项目,在克隆版本上测试操作之后再继续。
要恢复为默认包配置,请从 Help 菜单中选择 Reset Packages to defaults。
在执行最终更改之前,您也可以测试是否可以恢复为默认包:
要克隆项目,请复制粘贴项目文件夹,然后重命名项目文件夹以便于识别(例如,如果您的项目名为 MyProject
,则可以使用类似 clone_MyProject
的名称)。
加载新克隆的项目。
从 Help 菜单中,选择 Reset Packages to defaults。
根据项目的大小,这可能需要几分钟。
检查是否成功重置了包。如果成功,则表示您可以安全地对原始项目执行操作。
如果您尝试从注册表安装新的包但无法安装,可能是由于权限问题所致。
You must have full permissions on the cache folder:
C:\Users\yourname\AppData\Local\Unity\cache
~/Library/Unity/cache
~/.config/unity3d/cache
有时,学校、政府机关或受网络保护的工作场所等机构环境会设置代理服务器来控制网络与互联网之间的通信,并使用自己的服务器证书,而 Unity 或 Package Manager 无法识别这些证书。请与您的网络管理员联系。
See Repository not found.
If your installation drive is out of space or low on space, consider changing the location of the package caches:
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 encounter this message, try these solutions:
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:
In both cases, Package Manager considers the package to be potentially malicious.
When you encounter an invalid signature, you can try to install a different version of the package. You should also avoid using Unity packages from a registry other than the Unity Registry.
If you are sharing a Unity package that contains a fix, consider using a Git URL or embedding the package in your project.
如果尝试从 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(大型文件存储)的包,则可能会看到以下错误消息:
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,请访问代码仓库的页面,然后通过 Clone 按钮复制 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
如果您尝试从需要身份验证的专用代码仓库安装包,则在 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 解决方案中建议的解决方法之一。
SSH 使用一对公有和私有 SSH 密钥。可以将公有 SSH 密钥添加到 Bitbucket、GitHub 或 GitLab,之后无需输入用户名和密码即可访问代码仓库。
但是,如果您设置了一个口令短语来保护 SSH 密钥的安全,则仍然需要在终端或对话框中输入该口令短语以便授权密钥。在这种情况下,可以使用 SSH 代理,它可解锁您的 SSH 密钥以代表您向 Package Manager 进行身份验证。
Package Manager 没有提供用来输入 HTTP(S) 用户名和密码的交互式终端或对话框。要绕过这一点,请使用下列其中一种变通方法:
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 machine that is protected by a passphrase.
此问题的解决方案是设置 SSH 代理,它可解锁您的 SSH 密钥以代表您向 Package Manager 进行身份验证。按照与您操作系统对应的部分中的说明进行操作:
原生 Windows OpenSSH 版本的 ssh-agent 比 Git for Windows 默认提供的版本效果更好。此过程说明如何设置 OpenSSH 客户端并将密钥添加到其 ssh-agent。如果使用 Git for Windows,则还可以使原生 Windows OpenSSH 优先于 Git for Windows SSH 代理:
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+.
检查 %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
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>
如果您不记得密钥名称,则可以要求代理列出它们:
ssh-add -l
如果您安装了 Git for Windows,请重置 %GIT-SSH%
环境变量以确保 Git 始终使用原生 Windows OpenSSH 版本的 ssh-agent:
[Environment]::SetEnvironmentVariable("GIT_SSH", "$((Get-Command ssh).Source)", [System.EnvironmentVariableTarget]::User)
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:
Prior to macOS 12, use:
ssh-add -K ~/.ssh/<your-secure-ssh-key-name>
Starting with macOS 12, 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>
重新启动计算机以应用这些更改。
如果您尝试从代码仓库将 Git 依赖关系更新到较新版本,但它不起作用,则可能是因为您的 Git 依赖关系已锁定。如果要从代码仓库将 Git 依赖关系更新到较新版本,请使用 Add package from git URL 按钮并输入 Git URL。有关更多信息,请参阅已锁定的 Git 依赖项。
If you see 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 contains a lot of asset data, it might take a lot of time and bandwidth to re-download everything.
并非所有注册表提供程序都与 Unity 的 Package Manager 兼容。如果添加的包注册表服务器未实现 /-/v1/search
或 /-/all
终端,则范围注册表与 Unity 的 Package Manager 不兼容,不会出现在 Package Manager 窗口的 My Registries 上下文中。
在构建期间,如果有许多关于缺失行为的错误,则 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 的更多信息,请参阅托管代码剥离。