Git 依赖项
当包管理器从 Git 存储库获取包时，它会将包本地添加到您的项目中。这允许您测试未发布的更改，但您无法使用它来贡献到该 Git 存储库。要将现有的本地 Git 存储库设置为项目中的依赖项，请改用本地 Git 存储库的路径。
注意：您无法在package.json 文件中指定Git 依赖项包管理器直接从 Git 存储库而不是从包注册表中检索 Git 依赖项。Git 依赖项使用 Git URL 引用而不是版本，并且无法保证包的质量、稳定性、有效性，甚至无法保证其package.json文件中声明的版本是否符合关于此包正式发布版本的语义版本控制规则。更多信息
参见术语表，因为包管理器不支持包之间的 Git 依赖项。它仅支持项目的 Git 依赖项，因此您只能在项目的manifest.json 文件中声明 Git 依赖项。
提示：如果您想将 Git 依赖项更新到存储库中的特定版本（修订版），请参阅锁定 Git 依赖项。
本节包含以下主题
要求
要在项目中使用 Git 依赖项，请确保您已在计算机上安装了Git 客户端（最低版本 2.14.0），并且您已将 Git 可执行文件路径添加到 PATH 系统环境变量。
警告：Unity 已测试包管理器与 Git 2.14.0 及更高版本配合使用。如果您使用低于 2.14.0 的 Git 版本，Unity 无法保证结果。
如果存储库使用Git LFS跟踪文件，请确保 Git LFS 客户端也安装在您的机器上。如果未安装，则包管理器无法检索存储在 LFS 服务器上的文件，而是检出 LFS 指针文件，没有任何错误或警告消息。
您可以使用包管理器窗口直接从 Git 存储库安装包。有关更多信息，请参阅从 Git URL 安装。
Git URL
包管理器支持所有Git 协议，除了本地文件路径。要将 Git URL 指定为依赖项，请将要添加的包的名称与 Git URL 一起添加到项目清单每个 Unity 项目都有一个项目清单，它充当包管理器的入口点。此文件必须位于<project>/Packages目录中。包管理器使用它来配置许多内容，包括该项目的依赖项列表以及要查询包的任何包存储库。更多信息
参见术语表中。例如，这演示了如何使用不同的协议指定远程 Git
{
"dependencies": {
"com.mycompany.mypackage1": "https://github.example.com/myuser/myrepository1.git",
"com.mycompany.mypackage2": "ssh://[email protected]/myuser/myrepository2.git",
"com.mycompany.mypackage3": "file://localhost/github.example.com/myuser/myrepository3.git",
"com.mycompany.mypackage4": "git://github.example.com/myuser/myrepository4.git",
etc.
}
}
包管理器通过查找存储库路径末尾的.git文件扩展名来识别格式化为 URL 的依赖项是 Git URL。一些 Git 存储库托管服务不支持带有此扩展名的 URL，而其他服务则强制执行此扩展名。出于此原因，Git 依赖项语法允许您在使用GIT 协议时省略扩展名，或者在HTTP/HTTPS、SSH或FILE URL 中添加特殊的git+前缀。
注意：git+前缀是manifest.json文件中指示依赖项基于 Git 的特殊标记。包管理器在克隆存储库时不会将其传递给 Git。
有关 Git 支持的 URL 格式的更多信息，请参阅 gitclone命令的文档。有关 Git 使用的协议之间差异的概述，请参阅Git 使用协议的文档。
您还可以对 Git 依赖项使用扩展语法
-
如果您想要的包不在存储库的根目录下，则可以在存储库中指定包的子文件夹的路径。仅当您想要的包不在存储库的根目录下时，才需要这样做。例如，字符串
?path=/folder1/folder2在"https://github.example.com/myuser/myrepository.git?path=/folder1/folder2".有关更多信息，请参阅指定存储库子文件夹中的包。
-
您可以指定 Git 修订版，它可以是标签、分支名称或特定的提交哈希值以锁定。这确保包管理器始终加载该确切的修订版。如果您未指定修订版，则包管理器会在默认分支和最新提交处克隆存储库并锁定该修订版。例如，字符串
#v2.0.0在"https://github.example.com/myuser/myrepository.git#v2.0.0"有关更多信息，请参阅指定 Git 修订版。
使用 HTTP/HTTPS 协议
您可以使用 HTTPS 协议和完整 URL
{
"dependencies": {
"com.mycompany.mypackage": "https://github.example.com/myuser/myrepository.git"
}
}
如果您的 Git 服务器不支持.git扩展名，您可以添加特殊的git+前缀，无论是否带有扩展名
{
"dependencies": {
"com.mycompany.mypackage1": "git+https://github.example.com/myuser/myrepository1.git",
"com.mycompany.mypackage2": "git+https://github.example.com/myuser/myrepository2"
}
}
注意：或者，您可以使用 GIT 协议代替git+前缀。有关更多信息，请参阅使用 GIT 协议。
如果存储库是公开可访问的，则建议使用 HTTPS 方案与用户共享 Git URL，因为您可以直接从 Git 存储库托管服务网页复制粘贴 URL。
如果存储库不是公开可访问的并且您正在使用 HTTPS，则存储库服务器将无法验证您的身份，因为您无法与服务器交互以提供您的凭据。在这种情况下，编辑器会通知您身份验证失败。
要解决这些身份验证问题，您可以：
- 使用Git 凭据帮助程序预先进行身份验证。有关更多信息，请参阅使用 HTTPS Git URL 使用私有存储库。
- 改用SSH 协议。如果您使用 Git 存储库托管服务设置和配置了 SSH 密钥对，则包管理器可以代表您无缝地验证请求。
使用 SSH 协议
您可以使用 SSH 协议和完整 URL
{
"dependencies": {
"com.mycompany.mypackage": "ssh://[email protected]/gitproject/com.mycompany.mypackage.git"
}
}
如果您的 Git 服务器不支持.git扩展名，您可以添加特殊的git+前缀，无论是否带有扩展名
{
"dependencies": {
"com.mycompany.mypackage1": "git+ssh://[email protected]/myuser/myrepository1.git",
"com.mycompany.mypackage2": "git+ssh://[email protected]/myuser/myrepository2"
}
}
注意：或者，您可以使用 GIT 协议代替git+前缀。有关更多信息，请参阅使用 GIT 协议。
您还可以使用类似 SCP 的简写，包管理器始终将其识别为 Git 依赖项
{
"dependencies": {
"com.mycompany.mypackage": "[email protected]:gitproject/com.mycompany.mypackage.git"
}
}
在 Windows 上使用 PuTTY
当您使用 SSH 进行身份验证时，Git 会使用默认位置的密钥。但是，如果您在 Windows 上使用PuTTY作为 SSH 客户端，则需要配置GIT_SSH环境变量以使其指向plink.exe。
使用 SSH 进行身份验证
如果您想使用 SSH 协议，则需要在 Unity 之外设置 SSH 密钥。有关为特定主机设置身份验证的更多信息，请参阅Bitbucket、GitLab和GitHub的帮助页面。
注意：如果您使用密码加密了 SSH 密钥，则包管理器将无法检索包，因为它不提供在终端或命令行中输入密码的方法。在这种情况下，编辑器会通知您身份验证失败。有关使用身份验证代理的信息，请参阅使用受密码保护的 SSH 密钥与 SSH Git URL。有关使用ssh-agent进行身份验证的其他信息，请参阅SSH 解决方案。
使用 FILE 协议
除非 Git URL 格式正确，否则包管理器不会将带有file:前缀的 Git URL 识别为 Git 依赖项。这意味着您必须使用git+file:协议或使用file:协议的.git后缀
{
"dependencies": {
"com.mycompany.mypackage1": "git+file://github.example.com/myuser/myrepository1",
"com.mycompany.mypackage2": "git+file:///github.example.com/myuser/myrepository2",
"com.mycompany.mypackage3": "file:///github.example.com/myuser/myrepository3.git"
}
}
注意：或者，您可以使用 GIT 协议代替git+前缀。有关更多信息，请参阅使用 GIT 协议。
包管理器将任何其他语法解释为本地路径。
使用 GIT 协议
包管理器识别git:协议，无论是否带有.git路径后缀
{
"dependencies": {
"com.mycompany.mypackage1": "git://github.example.com/myuser/myrepository1.git",
"com.mycompany.mypackage2": "git://github.example.com/myuser/myrepository2"
}
}
GIT 协议不需要也不支持git+前缀。
扩展语法
您可以使用扩展语法来识别特定的 Git 修订版、子文件夹中的包或两者。
您可以将扩展语法与 Unity 支持的任何 Git 协议一起使用。
指定 Git 修订版
要声明您希望包管理器克隆的特定修订版，请在 URL 末尾添加以数字符号 (#) 为前缀的修订版
{
"dependencies": {
"com.mycompany.mypackage1": "https://github.example.com/myuser/myrepository1.git#revision",
"com.mycompany.mypackage2": "git+https://github.example.com/myuser/myrepository2#revision"
}
}
修订版可以是任何标签、分支或提交哈希值。您必须提供完整的提交哈希值。Unity 不支持缩短的 SHA-1 哈希值。此表显示了指定修订版的示例
| 语法 | URL 示例 |
|---|---|
| 最新默认分支 | "https://github.example.com/myuser/myrepository.git" |
| 特定分支 | "https://github.example.com/myuser/myrepository.git#my-branch" |
| 特定版本 | "https://github.example.com/myuser/myrepository.git#v2.0.0" |
| 提交哈希值 | "https://github.example.com/myuser/myrepository.git#9e72f9d5a6a3dadc38d813d8399e1b0e86781a49" |
指定存储库子文件夹中的包
如果您使用 Git URL 语法指定存储库，则包管理器会假设包必须位于存储库的根目录下。但是，一些包未位于其存储库的根级别，并且一些存储库包含多个包。
您可以在 Git URL 中使用path查询参数来通知包管理器在哪里查找包。您指定的路径必须相对于存储库的根目录，并且您指定的子文件夹必须包含包清单每个包都有一个清单，它向包管理器提供有关包的信息。清单包含诸如包的名称、版本、用户描述、对其他包的依赖项（如果有）以及其他详细信息等信息。更多信息
参见术语表（package.json文件）。
要为 Git 依赖项指定存储库子文件夹，请使用path查询参数
{
"dependencies": {
"com.mycompany.mypackage": "https://github.example.com/myuser/myrepository.git?path=/subfolder"
}
}
在这种情况下，包管理器会注册位于指定存储库子文件夹中的包，并忽略存储库的其余部分。
有时存储库包含几个相关的包。如果您想从同一个存储库中添加多个包，则必须在项目清单中添加两个单独的条目
{
"dependencies": {
"com.mycompany.mypackage1": "https://github.example.com/myuser/myrepository.git?path=/subfolder1",
"com.mycompany.mypackage3": "https://github.example.com/myuser/myrepository.git?path=/subfolder2/subfolder3"
}
}
注意：如果您多次指定相同的存储库，包管理器会多次克隆相同的存储库，这会导致性能降低和网络使用量增加。
同时指定修订版和路径
您可以使用 Unity 支持的任何 Git 协议指定路径和修订版。但是，path查询参数始终位于修订版锚点之前。反向顺序会失败。这是一个使用正确顺序的示例
{
"dependencies": {
"com.mycompany.mypackage": "https://github.example.com/myuser/myrepository.git?path=/example/folder#v1.2.3"
}
}
锁定 Git 依赖项
包管理器的核心原则之一是确定性。如果您与其他用户共享您的项目，则包管理器应安装相同的一组包依赖项和版本，包括它从 Git 中获取的包。为了实现这一点，包管理器通过使用锁定文件来跟踪 Git 依赖项的提交哈希值。
当您添加一个 Git 依赖项，并且其版本设置为分支或标签时，包管理器会获取相应的提交哈希值并将其存储在锁定文件中。随着时间的推移，分支和标签可能会指向 Git 存储库中的不同提交。例如，一个分支可能会添加新的提交。
要将包更新到分支或标签指向的不同提交，请使用从 Git URL 安装包按钮并输入 Git URL。您可以使用相同的 Git URL，因为当您提交新请求时，包管理器会忽略锁定的提交哈希值。但是，您也可以指定一个新的修订版本号、标签或分支作为版本。
或者，您可以使用带有Client.Add C# API 方法的脚本和该 Git URL。
Git LFS 支持
包管理器支持使用 Git LFS 的存储库的 Git 依赖项。由于 Git LFS 旨在以最少的配置开销工作，因此它支持 HTTPS 和 SSH 身份验证。
- 有关 HTTPS 身份验证的信息，请参阅使用 HTTP/HTTPS 协议。
- 有关 SSH 身份验证的信息，请参阅使用 SSH 协议。
如果用户需要身份验证并且没有有效的凭据来访问远程存储库，则检索存储在 LFS 服务器上的文件将失败。
包作者可以通过在存储库中的.lfsconfig配置文件中提供 URL 来帮助 Git LFS 客户端找到 LFS 服务器。有两种方法可以做到这一点。
# Option 1: global setting
[lfs]
url = ssh://git@HOSTNAME/path/to/repo.git
# Option 2: per-remote setting
[remote "origin"]
lfsurl = ssh://git@HOSTNAME/path/to/repo.git
如果存储库包含.lfsconfig文件，请确保将其包含在.npmignore文件中，以避免将其包含在包的发布版本中。
Git LFS 缓存
从 Unity 2021.2 开始，您可以选择启用 Git LFS 缓存供包管理器在检出基于 Git 的依赖项时使用。这样可以避免每次检出存储库的不同版本时都必须下载相同的文件。
包管理器的 Git LFS 缓存与 Git 存储库的.git/lfs文件夹中的 Git LFS 缓存不同。包管理器无法使用默认的 Git 缓存，因为它不会在将包复制到项目缓存后保留克隆的存储库。
要启用包管理器的 Git LFS 缓存，请选择以下选项之一。
- 要启用 Git LFS 缓存并使用默认全局缓存根目录下的
git-lfs子文件夹作为其位置，请将UPM_ENABLE_GIT_LFS_CACHE环境变量设置为任何（非空）值。 - 要启用 Git LFS 缓存并为其使用自定义位置，请将
UPM_GIT_LFS_CACHE_PATH环境变量设置为自定义路径。当您设置位置时，Git LFS 缓存选项会自动启用。
有关为全局缓存设置环境变量的更多信息，请参阅自定义全局缓存。
注意：当使用启用 Git LFS 的包时，此优化需要额外的磁盘空间。您需要确定哪种好处更大：Git LFS 文件缓存会占用磁盘空间，但可以避免您再次下载相同的文件。但是，某些情况下无法使用缓存并占用磁盘空间而不会重用文件。例如，您的 Git 依赖项可能会解析为引用不同 LFS 跟踪文件内容的版本，例如以下场景。
- 在多个项目中的依赖项中使用不同的 Git 版本
- 经常将包更新到包含不同更改的 LFS 文件的版本