文档

Unity 引擎

Unity 引擎

包管理器故障排除

获取有关包管理器故障排除的信息。
阅读时间23 分钟最后更新于 8 天前

本节提供ON以下问题的信息:
如果遇到可能与网络相关的问题,还可以运行 Unity 包管理器诊断工具。有关更多信息,请参阅诊断网络问题。

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

包管理器遇到问题时会在包管理器窗口中显示报错指示。

System 宽问题

  • 网络连接问题
    当包管理器检测到与指定包无关的问题时,状态栏中会显示错误消息。例如,如果包管理器无法访问包注册表服务器,它会在状态栏中显示以下 message:

    Network error message

  • 刷新资源错误(或刷新包错误)
    如果网络无法访问包册表服务Server,可能是因为网络连接出现问题。当您或系统管理员诊断并修复网络报错时,状态栏会清除。
    如果您的网络连接正常,但未登录 Unity 帐户,则包管理器不会显示 Any Asset Store(资源商店)包。当您尝试使用 My Assets 上下文时,包管理器会提示您登录:

    Logged out of Unity account

    单击列表面板中的登录按钮,通过 Unity Hub 登录 Unity 帐户。

包指定的问题

  • 如果指定的包在加载中或安装时出现问题(例如,当确定要加载的包版本时),则报错图标 (Error icon) 将显示在受损包 (A) Next 的列表面板中。要查找问题所在,请检查受损包的细节面板以查看详细的报错消息 (B):

    Dependency error message

包管理器 缺失或窗口无法Open

包管理器 Window可能会移出屏幕或被另一个Window隐藏。发生这种情况When,包管理器 窗口似乎failedOpen。在这种情况下,可以尝试重置窗口 Layout(窗口 > Layouts > 默认),然后再次重新打开包管理器窗口。
如果 包管理器 窗口仍未出现,请检查 Unity 控制台 窗口:
failed解析包:文件 [<project-path>/Packages/清单.json] 无效 json: 44:1 时出现意外令牌“}” }
此报错 message 表示
manifest.json
文件的格式不正确。它还告诉您 包管理器 failed解析文件的数量,以便修复 json。您可以使用几个在线验证器来尝试纠正问题。Save更正的文件后,Unity 会重新加载 包管理器 窗口。
如果从早期版本的 Unity Editor 升级,则清单文件可能存在Other问题:
  • 从 2019.3 开始,
    manifest.json
    文件不应包含对 COM. unity.包-管理员-UI 包的任何引用。从清单的依赖项列表中移除以线:
    "com.unity.package-manager-ui":"2.1.1",
  • 检查 Project 清单是否使用**“exclude”**作为包版本。这是 dependencies 属性的过时值。如果查找此类 Any 行,请移除整条线。包管理器 仅安装作为依赖关系项显式包含在Project中的包,因此,一旦移除该条目,包管理器 就会忽略该包并且不安装它。

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

将Project升级到较新的 Unity VersionWhen,包管理器 会自动将不兼容的包更新为较新的兼容版本。但是,如果包无法编译,包管理器会在控制台窗口中显示报错消息。
要更正这些消息,请阅读报错消息并尽可能修复 Any 问题。例如,包可能缺失 ON 其他包或版本的依赖关系。在这种情况下,您可以尝试自己安装包。
还可以尝试以下顺序的解决方案,直到查找到可行的解决方案:
  • 备份然后删除 Project 下的
    Packages
    Folder。
  • 备份然后删除 Project 的
    Packages
    Folder 中的包源,仅留下
    manifest.json
    文件。然后尝试重新加载 Project。

包装失败

如果您尝试从注册表安装包但无法运行,可能是权限问题所致。
您必须拥有缓存文件夹的 ON 完全权限:
  • Windows(用户帐户):
    %LOCALAPPDATA%\Unity\cache\upm
  • Windows(System 帐户):
    %ALLUSERSPROFILE%\Unity\cache\upm
  • macOS
  • Linux
可能是网络问题。检查防火墙和代理 Settings。
有时,机构环境(例如学校、政府办公室或受网络保护的工作场所)会设置代理服务器来Control网络和互联网之间的流量,并使用自己的服务ServerCertificates,而这些证书无法被 Unity 或 包管理器 识别。与网络管理员联系。

无法从 Git 网址添加包

驱动器Space不足

如果您的安装驱动器空间不足或 ON Space 低,请考虑以下解决方案:

版本本没有signature

从作用域注册表获取 Unity 包When,可能会出现此message。Unity 会对其创建的包进行签名,但较旧的包除外,这些包不一定在更高版本中重新签名。如果将未签名的 Unity 包从作用域注册复制到另一个注册表,包管理器 无法确定包内容是否Safe并与原始包相同。
如果收到此 message,请尝试以下解决方案:
  • 使用包的另一个版本。
  • 从 Unity 注册表获取 Unity 包。
  • 如果您拥有作用域注册表,请make Unity 注册复制包的最新版本。

版本本没有有效的signature

重要
6000.0.66f2
之前的所有 6.0 版本都存在包管理器可以上报包无效的已知问题,即使它们具有有效的包 signature。
6000.0.66f2
及更高版本已修复此问题。更新这些构建之一以解决此问题。
有关 Unity Editor Other Versions 中此问题的信息,请参阅 Unity discussions。
包具有 signature 以确保内容在传输之前或传输过程中未更改。无效 signature 通常发生在以下情况:
  • 有人发布了经过修改的包 ON 自己的注册表。
  • 将文件传输到结束用户时发生报错。
在这两种情况下,包管理器都认为该包可能具有恶意。
收到无效signatureWhen,可以尝试安装其他版本的包。此外,应避免使用 Unity Registry Other 注册表中的 Unity 包。
如果要共享具有修复的 Unity 包,请考虑使用 Git 网址 或将包入到Project中。

未找到“Git”可执行文件

如果尝试从 Git 网址安装包,则会显示类似以下的 message:
无法执行 upm 操作:无法添加包https://github.example.com/myuser/myrepository.git未找到“Git”可执行文件。请ONSystem上安装 Git 并重新启动 Unity [NotFound]UnityEditor.EditorApplication:Internal_CallUpdateFunctions()

Git-lfs:未找到命令

如果要Download使用 Git LFS(大文件存储)的包,可能会收到以下报错message:
执行 Git 命令When错误。Git 过滤器process:未找到命令。
这表示计算机ON可能未安装 Git LFS。要make这一点,请ON命令线进行测试:
Git lfs 版本
如果命令返回如下内容,则会安装 Git LFS:
git-lfs/2.8.0 (GitHub; darwin amd64; go 1.12.7)
否则,您可以按照 Bitbucket GitHub 说明进行安装。

Git LFS 错误

包管理器支持从使用 Git 大文件存储 (LFS) 的 Repositories 安装包。Unity 最初会尝试浅克隆以提高性能,但在 Git LFS 需要When(例如获取未通告的对象When)会自动回退到完整代码仓库。
如果 Download 操作获取的是 Placeholder 指针文件而不是实际文件内容,最有可能的罪魁祸首可能是
.gitattributes
文件的位置。Unity 支持
.gitattributes
文件的两个位置:代码仓库的根和包目录的根。要降低问题风险:
  • 确保
    .gitattributes
    文件已正确 Configured,以确保仅使用 LFS 跟踪目标文件。
  • 避免将基本包代码或Assets置于 LFS 跟踪之下。如果必须使用 LFS 存储大型Assets,请将它们保持在 Unity 包之外(例如,在单独的代码代码仓库中),然后使用其他方法(例如 AssetBundles 或专用资源代码仓库)将它们导入 Unity。

未找到代码仓库

如果包管理器找不到指定的代码仓库,Unity 控制台会显示报错 message:
无法执行 upm 操作:无法添加包 [https://mycompany.github.com/gitproject/com.mycompany.mypackage.git]: 执行 Git 命令时出错。致命:未找到代码仓库“https://mycompany.github.com/gitproject/com.mycompany.mypackage.git/” NotFoundUnityEditor.EditorApplication:内部_CallUpdateFunctions()(位于 /User/builduser/buildslave/Unity/版本/Editor/Mono/EditorApplication.cs:310)
Check您的拼写。要make使用的 网址 正确无误,请转到代码仓库的Page,然后从 Clone 按钮复制 网址:

Where to copy the URL on GitHub (A) and GitLab (B)

单击 ON GitHub (A) 或 GitLab (B) 网址右侧的按钮,将网址复制到剪贴板。
如果代码仓库的位置正确,则网址可能存在另一个问题:
  • 如果您的目标是指定的修订版本,请make您的修订版本排在最后。例如:
    https://github.example.com/myuser/myrepository1.git#revision
  • 如果您的目标是修订版本,而包不在根目录,请确保
    path
    查询参数位于修订 Anchor 之前。例如:
    https://github.example.com/myuser/myrepository.git?path=/example/folder#v1.2.3
如果代码仓库的位置和网址正确,请检查
PATH
System Environment 变量。确保
PATH
变量包含 Git
cmd
目录(Windows)和 Git
bin
目录(Windows、macOS)的条目。包管理器进程需要在
PATH
变量中输入这些条目。

无法读取用户名:Terminal 提示 Disabled

如果要从需要身份Authentication的private代码代码仓库包,Unity 控制台台中会显示一条类似以下message:
无法执行 upm 操作:无法添加包 [https://mycompany.github.com/gitproject/com.mycompany.mypackage.git]: 执行 Git 命令时的错误。致命:无法读取“https://mycompany.github.com”的用户名: Terminal 提示 Disabled NotFoundUnityEditor.EditorApplication:内部_CallUpdateFunctions()(位于 /User/builduser/buildslave/Unity/版本/Editor/Mono/EditorApplication.cs:310)
通常,出现此message的原因是 包管理器 未提供交互式Terminal或对话框,无法在此进入 HTTP 用户名和密码,也无法输入密码短语来解锁 SSH 密钥:
  • 使用 HTTP(S) 时,每次登录 Bitbucket、GitHub 或 GitLab 时,都需要在 Terminal 或对话框中输入您的用户名和密码。但是,包管理器 没有提供交互式Terminal或对话框,无法在此进入 HTTP(S) 的用户名和密码。
    要绕过此问题,请使用 Solutions for HTTPS 中建议的解决方法之一。
  • SSH 使用一对 public 和 private SSH Keys。您可以将公有 SSH 密钥添加到 Bitbucket、GitHub 或 GitLab,然后访问 Repositories,而无需输入用户名和密码。
    但是,如果设置了密码短语来保持 SSH 密钥的Safe,则仍必须在Terminal或对话框中进入该密码短语来Authorize您的Key。在这种情况下,您可以使用 SSH Agent 解锁 SSH 密钥,代表您向包管理器进行身份验证。

HTTPS 解决方案

包管理器不提供可以进入 HTTP(S) 用户名和密码的交互式 Terminal 或对话框。Bypass过此问题,请使用以下变通方法之一:
  • 请遵循有关使用私有代码仓库和 HTTPS Git URL 的说明以及使用受密码短语保护的 SSH Keys 和 SSH Git URL 的说明。
  • 使用凭据管理员(适用于 Git Credential Manager for Windows 或 OSXKeyChain)。凭据管理器可手柄发送密码,而不必使用 Terminal 或命令提示符。
  • 使用终端或命令提示符中的 Git 凭据,然后从同一终端启动 Hub,以便 Unity 可以访问缓存或存储的凭据。
  • 使用 SSH 进行身份验证。如果在没有密码短语的情况下设置 SSH 密钥,包管理器 不必解密密钥即可向 Git Server器进行身份验证。如果您决定使用密码短语来增加 SECURITY,则可以在 macOS 或 Windows ON 使用 SSH-Agent 来解决 Authentication 问题。

SSH 解决方案

如果使用 SSH 协议按 Git 网址安装包,可能会收到 Git 的 Authentication 报错。通常在使用密码短语保护的本地计算机ON设置private SSH 密钥这种情况。
此问题的解决方案是设置一个 SSH Agent,该代理可以解锁您的 SSH 密钥以代表您向 包管理器 ON身份验证。请遵循与 Operating System 对应的部分中的说明:

为 Windows 设置 OpenSSH

SSH Agent 的内置 Windows OpenSSH 版本比 Git for Windows 默认情况下可用的版本更好。此过程说明如何设置 OpenSSH 客户端并将 Key 添加到其 SSH Agent。如果使用 Git for Windows,还可以将内置的 Windows OpenSSH 优先于 Git for Windows SSH Agent:
  1. make安装了 OpenSSH Client。为此,请在 Windows Settings Optional Features 窗口(Start > Settings,然后搜索“Optional Features”)中搜索。这适用于 Windows 10+。
  2. 检查
    %PATH%
    Environment 变量以确保显示内置的 Windows OpenSSH 位置(例如,
    C:\WINDOWS\System32\OpenSSH\
    )。
    注意
    如果已在使用 Git for Windows,请确保内置的 Windows OpenSSH 位置出现在
    %PATH%
    变量中的 Git for Windows SSH 位置之前。这可确保 Windows 使用内置的 Windows OpenSSH Agent 而不是 Git for Windows SSH Agent。
  3. 在 PowerShell Terminal 中,启动
    ssh-agent
    进程并确保它自动启动:
    # Set the ssh-agent service to start automatically and manually start it nowGet-Service SSH-Agent | 设置-服务 -StartupType Automatic# Run the ssh-agent process to start the ssh-agent servicessh-agent
  4. 将 Key 导入 SSH-agent。为此,请在命令行上运行
    ssh-add
    ,然后按照说明进行操作。默认情况下,Agent 会添加
    %USERPROFILE%\.ssh\id_rsa
    Key 并提示您输入密码。
    # Import the keyssh-add
    要使用不同的 Key,可以将其指定为参数:
    # Set the ssh-agent service to start automatically and manually start it nowSSH 添加<your-secure-ssh-key-name>
    如果不记得Key的Name,请使用以下命令列表密钥:
    ssh-add -l
  5. 如果安装了适用于 Windows 的 Git,请重置
    %GIT-SSH%
    Environment 变量以确保 Git 始终使用 SSH Agent 的内置 Windows OpenSSH 版本:
    [Environment]::SetEnvironmentVariable("Git_SSH", "$((Get-Command SSH).音频源)", [System.EnvironmentVariableTarget]::用户)

将 SSH Keys 添加到 SSH Agent for macOS

使用
ssh-add
命令将 SSH Keys 添加到 macOS System running ON 的 SSH-Agent。使用的命令参数取决ON macOS 版本:
  • ON macOS 11 及更早版本,使用:
    ssh-add -K ~/.ssh/<your-secure-ssh-key-name>
  • ON macOS 12 及更高版本,使用:
    ssh-add --apple-use-keychain ~/.ssh/<your-secure-ssh-key-name>
运行此命令后,Terminal会要求输入密码来解锁 SSH 密钥,然后将它添加到 macOS 密密钥链中。但是,重新启动系统后,SSH-agent 中存储的每个 Key 都会重置。
为了确保在重新启动 System 后无需重新进入密码,请打开
~/.ssh/config
文件(如果未查找,则创建一个),然后添加以下内容:
"host": [ UseKeychain Yes AddKeysToAgent Yes IdentityFile ~/.ssh/<your-secure-ssh-key-name>
重新启动计算机以Apply这些更改。

无法更新 Git 版本

如果尝试从代码仓库将 Git 依赖关系更新到更高版本,但效果不佳,可能是因为 Git 依赖关系锁定。如果要从代码仓库将 Git 依赖关系更新到更高版本,请使用 Add package from Git URL 按钮并进入 Git URL。有关更多信息,请参阅 Locked Git 依赖项。

'failed解析 My Assets 上下文中的 http response'

如果在尝试从 Asset Store(资源商店)下载资源包时在控制台窗口中收到以下消息,则资源包缓存可能存在问题:
[PackageManager] Error Failed to parse response. UnityEditor.AsyncHTTPClient![:D](https://forum.unity.com/styles/default/xenforo/clear.png)one(State, Int32)
要解决此问题,请从下载资源包文件位置删除所有下载的资源,然后再次尝试下载资源。
警告
如果您的项目有很多资源数据,重新下载所有内容可能需要很多时间和带宽。

包管理器 窗口中缺失“My Registries”

并非All注册表提供程序都与 Unity 的 包管理器 兼容。如果您添加的包注册表服务器无法实现
/-/v1/search
或
/-/all
终端,则表明您的范围注册表与 Unity 的包管理器不兼容,并且不会出现在包管理器窗口的导航面板的 My Registries 下。

缺失 MonoBehaviour 错误

构建时,如果存在大量有关缺失行为的错误,UnityLinker 可能会错误地剥离它认为未引用的组件。这样做的原因通常是剥离关卡过于激进。例如,如果 AssetBundle 中的预制件件引用了 2D SpriteShape 包的 SpriteShape 组件,则该Object可能缺失并可能会Generate编译器警告。
要解决此问题,可以降低 UnityLinker 的剥离关卡,或者在
link.xml
文件中声明包的程序集,以免它们被剥离:
<linker> <assembly fullname="Unity.2D.SpriteShape.Runtime" preserve="all"/> <assembly fullname="Unity.2D.Common.Runtime" preserve="all"/> </linker>
有关 ON 剥离级别和 UnityLinker 的更多信息,请参阅托管代码剥离。

其他资源