文档

Unity 引擎

Unity 引擎

Git 依赖关系简介

了解从 Git 代码仓库获取包产生的依赖关系。了解使用于从 Git 代码仓库获取包的协议和扩展语法。
阅读时间19 分钟最后更新于 8 天前

包管理器 从 Git 代码仓库获取包When,会将包添加到Project的本地。这允许您测试未发布的更改,但无法将使用于为该 Git 代码仓库做出贡献。要将现有的本地 Git 代码仓库设置为 Project 中的依赖关系,请改用本地 Git 代码仓库的路径。
注意
无法在包。json文件中指定 Git 依赖关系,因为包管理器不支持包之间的 Git 依赖关系。它仅支持 Project 的 Git 依赖关系,因此只能在项目的 清单.json 文件中声明 Git 依赖关系。
提示
如果要将 Git 依赖关系更新到代码仓库中的指定版本(修订版本),请参阅[锁定的 Git 依赖关系](# Git-locks)。
本节包括以下主题:

要求

要在项目中使用 Git 依赖项,请确保计算机上安装了 Git 客户端(最低版本 2.14.0),并且已将 Git 可执行文件路径添加到路径 System Environment 变量。
警告
Unity 测试了包管理器与 Git 2.14.0 及更高版本配合使用。如果使用低于 2.14.0 的 Git 版本,Unity 不能保证结果。
如果代码仓库使用 Git LFS 跟踪文件,请确保计算机上也安装了 Git LFS 客户端。如果未安装,包管理器无法检索 ON LFS Server 存储的文件,而是签出没有 Any 报错或 Warning 消息的 LFS 指针文件。
您可以使用 包管理器 窗口直接从 Git 代码仓库包如需了解更多信息,请参阅从 Git 网址安装。

Git URL

包管理器支持所有 Git 协议,本地文件路径异常除外。要将 Git 网址 指定为依赖关系项,请向Project清单中添加要添加的包的Name(使用 Git 网址,而不是版本数量或本地文件路径)。例如,下面演示了如何使用不同的协议指定远程 Git:
{ "dependencies": { "com.mycompany.mypackage1": "https://github.example.com/myuser/myrepository1.git", "com.mycompany.mypackage2": "ssh://git@github.example.com/myuser/myrepository2.git", "com.mycompany.mypackage3": "file://localhost/github.example.com/myuser/myrepository3.git", "com.mycompany.mypackage4": "git://github.example.com/myuser/myrepository4.git", 等等。 }}
包管理器通过在代码仓库路径结束时查找
.git
文件扩展名来识别网址格式的依赖关系是 Git 网址。某些 Git 代码仓库管Services不Support具有此扩展名的 URL,而Others服务会强制执行此扩展名。因此,如果使用 Git 协议,或者在 HTTP/HTTPS、SSH 或文件网址中添加特殊
git+
前缀,Git 依赖关系语法允许您省略扩展。
注意
git+
前缀是
manifest.json
文件中的特殊标记,指示依赖关系基于 Git。包管理器 在克隆代码仓库When不会将通道 Git。
有关 Git 支持的 URL Format 的更多信息,请参阅 Git clone 命令的文档。有关 Git 使用的协议之间的区别的 Overview,请参阅 Git 使用协议文档。
还可以对 Git 依赖关系使用扩展语法:
  • 如果需要的包不在代码代码仓库的根目录,则可以在代码仓库中指定包的子文件夹的路径。仅当所需的包在代码代码仓库的根目录时,才有必要这样做。例如,字符串
    ?path=/folder1/folder2
    于:
    "https://github.example.com/myuser/myrepository.git?path=/folder1/folder2"
    有关更多信息,请参阅在子文件夹中指定包。
  • 您可以指定 Git 修订版,它可以是标签、BRANCHName或要锁定的指定的提交哈希。这样可以确保包管理器始终加载该确切的修订版本。如果未指定修订版本,包管理器 会在默认BRANCH和最新提交位置克隆代码代码仓库,并锁定到该修订版本。例如,字符串
    #v2.0.0
    于:
    "https://github.example.com/myuser/myrepository.git#v2.0.0"
    有关更多信息,请参阅指定 Git 修订版本。

使用 HTTP/HTTPS 协议

您可以使用带有完整网址的 HTTPS 协议:
{ "dependencies": { "com.mycompany.mypackage": "https://github.example.com/myuser/myrepository.git" }}
如果您的 Git Server 不支持
.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 协议](# Git-Git)。
如果代码代码仓库可供公众访问,则 HTTPS 是与Users共享 Git URL 的推荐方案,因为您可以直接从 Git 代码仓库管服务Page复制和粘贴 网址。

Copy the URL from the package repository

如果代码仓库不可公开访问并且您正在使用 HTTPS,则代码仓库 Server 无法对您进行身份验证,因为您无法与 Server 交互以提供凭据。在这种情况下,Editor 会通知您身份Authenticationfailed。
要解决这些 Authentication 问题,您可以:
  • 使用 Git 凭据辅助程序预先进行身份验证。有关更多信息,请参阅将 private Repositories 与 HTTPS Git URL 结合使用。
  • 改用 SSH 协议。如果您使用 Git 代码仓库托管服务设置和配置了 SSH 密钥对,则包管理器可以代表您无缝验证请求。

使用 SSH 协议

您可以使用 SSH 协议以及完整的网址:
{ "dependencies": { "com.mycompany.mypackage": "ssh://git@mycompany.github.com/gitproject/com.mycompany.mypackage.git" }}
如果您的 Git Server 不支持
.git
扩展,则可以添加特殊
git+
前缀(无论是否包含扩展):
{ "dependencies": { "com.mycompany.mypackage1": "git+ssh://git@github.example.com/myuser/myrepository1.git", "com.mycompany.mypackage2": "git+ssh://git@github.example.com/myuser/myrepository2" }}
注意
或者,可以使用 Git 协议而不是
git+
前缀。有关更多信息,请参阅[使用 Git 协议](# Git-Git)。
还可以使用 SCP 类速记,包管理器始终将其识别为 Git 依赖关系:
{ "dependencies": { "com.mycompany.mypackage": "git@mycompany.github.com:gitproject/com.mycompany.mypackage.git" }}

ON Windows 使用 PuTTY

使用 SSH 进行身份验证When,Git 位置但是,如果将 PuTTY 用作 ON Windows 的 SSH 客户端,则需要配置
GIT_SSH
Environment 变量以使其指向
plink.exe
。

使用 SSH 进行身份验证

如果要使用 SSH 协议,需要在 Unity 外部设置 SSH Keys。有关为指定主机设置 Authentication ON 的更多信息,请参阅 Bitbucket、GitLab 和 GitHub 的帮助页面。
注意
如果您使用密码短语加密了 SSH 密钥,包管理器 无法检索包,因为它没有提供在Terminal或命令线进入密码短语的方法。在这种情况下,Editor 会通知您身份Authenticationfailed。有关使用 Authentication Agent 的信息,请参阅将受密码短语保护的 SSH Keys 与 SSH Git URL 结合使用。有关使用 SSH Agent 进行 Authentication 的其他信息,请参阅SSH 解决方案。

使用文件协议

包管理器无法将带有
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)。
包管理器将 Any Other 语法解释为本地路径。

使用 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 支持的Any Git 协议结合使用。

指定 Git 修订版

要声明要包管理器克隆的指定修订版本,请在网址末尾添加以数量符号 (
#
) 为前缀的修订版本:
{ "dependencies": { "com.mycompany.mypackage1": "https://github.example.com/myuser/myrepository1.git#revision", "com.mycompany.mypackage2": "git+https://github.example.com/myuser/myrepository2#revision" }}
修订版可以是 Any 标签、BRANCH 或提交哈希。您必须提供完整的提交哈希。Unity 不Support缩短 SHA-1 哈希。表显示了用于指定修订版的示例:

语法

'Url'(示例:****)

默认BRANCH
"https://github.example.com/myuser/myrepository.git"
指定的BRANCH
"https://github.example.com/myuser/myrepository.git#my-branch"
指定的标签
"https://github.example.com/myuser/myrepository.git#tag-pointing-to-package-version"
提交哈希
"https://github.example.com/myuser/myrepository.git#9e72f9d5a6a3dadc38d813d8399e1b0e86781a49"

在代码仓库的子文件夹中指定包

如果使用 Git URL 语法指定代码代码仓库,包管理器 会假定包必须位于代码代码仓库的根目录。但是,有些包并不位于其代码仓库的根关卡,有些代码Repositories包含多个包。
您可以使用 Git 网址中的
path
查询参数通知包管理器查找包的位置。指定的路径必须相对于代码仓库的根,并且指定的子文件夹必须包含包清单(
package.json
文件)。
要为 Git 依赖关系指定代码仓库子文件夹,请使用
path
查询参数:
{ "dependencies": { "com.mycompany.mypackage": "https://github.example.com/myuser/myrepository.git?path=/subfolder" }}
在这种情况下,包管理器 会注册位于指定代码代码仓库文件夹中的包,并忽略代码代码仓库的REST部分。
有时,代码仓库包含多个相关的包。如果要从同一代代码仓库添加多个包,必须将两个单独的条目添加到Project清单中:
{ "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 支持的Any Git 协议指定路径和修订版本。但是,
path
查询参数始终位于修订 Anchor 之前。相反 Order 失败。以下是要使用的正确 Order 的示例:
{ "dependencies": { "com.mycompany.mypackage": "https://github.example.com/myuser/myrepository.git?path=/example/folder#v1.2.3" }}

锁定的 Git 依赖项

包管理器的核心原则之一是确定性。如果与其他 Users 共享 Project,则包管理器应安装相同设置的包依赖关系和版本,其中包括从 Git 获取的包。为了实现这一点,包管理器使用锁定文件跟踪 Git 依赖项的提交哈希。
添加修订版设置为BRANCH或标签的 Git 依赖关系When,包管理器 会获取相应的提交哈希以存储在锁定文件中。随着时间的推移,分支和标签可以点 Git 代码仓库ON的不同提交。例如,BRANCH 可以向其中添加较新的提交。
要将包更新为 BRANCH 或标签指向的不同提交,请使用 安装包 from Git URL 按钮并进入 Git URL。您可以使用相同的 Git 网址,因为 包管理器 会在您提交新建请求When忽略锁定的提交哈希。但是,也可以指定新建修订号、标签或 BRANCH 作为修订版本。
或者,也可以使用 Client 添加带有该 Git 网址的 C# API 方法。

Git LFS 支持

包管理器支持使用 Git 大文件存储 (LFS) 的 Repositories 中的 Git 依赖关系。但是,由于 Unity 使用浅克隆,因此并不总是能够正确获取 LFS 跟踪的文件。有时,包可能会导入 Placeholder 指针文件,而不是实际文件内容。有关更多信息,请参阅 Git LFS 错误。
由于 Git LFS 旨在以最少的配置开销工作,因此它同时支持 HTTPS 和 SSH Authentication:
如果Users需要Authentication并且没有具有访问远程代码代码仓库权限的有效凭据,则检索存储ON LFS Server上的文件会失败。
包作者可以通过在代码仓库中的
.lfsconfig
配置文件中提供网址来帮助 Git LFS 客户端找到 LFS Server。有两种方法可以做到这一点:
# Option 1: global setting##option-1:-global-setting[lfs] url = ssh://git@HOSTNAME/path/to/repo.git# Option 2: per-remote setting##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 的依赖项时使用。这样可以避免时间检查代码仓库都Download相同的文件。
包管理器的 Git LFS 缓存与 Git 代码仓库
.git/lfs
Folder 中的 Git LFS 缓存不同。包管理器 无法使用默认的 Git 缓存,因为它在将包复制到Project缓存后不会保持克隆的代码Repositories。
要为 包管理器 Enable Git LFS 缓存,请选择以下选项之一:
  • 要启用 Git LFS 缓存并使用默认全局缓存根下的
    git-lfs
    子文件夹作为其位置,请将
    UPM_ENABLE_GIT_LFS_CACHE
    Environment 变量设置为 Any(非空)值。
  • 要启用 Git LFS 缓存并为其使用自定义位置,请将
    UPM_GIT_LFS_CACHE_PATH
    Environment 变量设置为自定义路径。设置位置When,会自动已启用 Git LFS 缓存选项。
有关为全局缓存设置 Environment 变量的更多信息,请参阅自定义全局缓存。
注意
使用已启用 Git LFS 的When,此优化需要额外的磁盘Space。您需要决定哪个 Git LFS 文件缓存的优点更大,因为前者会占用磁盘Space,但会避免再次下载相同的文件。但是,在某些情况下,如果不重用文件,就无法 make 使用缓存和使用磁盘空间。例如,Git 依赖项可能会解析为引用不同 LFS 跟踪文件内容的修订版本,例如以下情形:
  • 在多个个Projects的依赖关系中使用不同的 Git 修订版
  • 经常将包更新为包含不同已更改 LFS 文件的修订版本

其他资源