Git 依赖关系简介
了解从 Git 代码仓库获取包产生的依赖关系。了解使用于从 Git 代码仓库获取包的协议和扩展语法。
阅读时间19 分钟最后更新于 8 天前
包管理器 从 Git 代码仓库获取包When,会将包添加到Project的本地。这允许您测试未发布的更改,但无法将使用于为该 Git 代码仓库做出贡献。要将现有的本地 Git 代码仓库设置为 Project 中的依赖关系,请改用本地 Git 代码仓库的路径。
本节包括以下主题:
要求
要在项目中使用 Git 依赖项,请确保计算机上安装了 Git 客户端(最低版本 2.14.0),并且已将 Git 可执行文件路径添加到路径 System Environment 变量。
如果代码仓库使用 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 代码仓库管Services不Support具有此扩展名的 URL,而Others服务会强制执行此扩展名。因此,如果使用 Git 协议,或者在 HTTP/HTTPS、SSH 或文件网址中添加特殊前缀,Git 依赖关系语法允许您省略扩展。
.gitgit+还可以对 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 不支持 扩展,则可以添加特殊 前缀(无论是否包含扩展):
.gitgit+{ "dependencies": { "com.mycompany.mypackage1": "git+https://github.example.com/myuser/myrepository1.git", "com.mycompany.mypackage2": "git+https://github.example.com/myuser/myrepository2" }}
如果代码代码仓库可供公众访问,则 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 不支持 扩展,则可以添加特殊 前缀(无论是否包含扩展):
.gitgit+{ "dependencies": { "com.mycompany.mypackage1": "git+ssh://git@github.example.com/myuser/myrepository1.git", "com.mycompany.mypackage2": "git+ssh://git@github.example.com/myuser/myrepository2" }}
还可以使用 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 客户端,则需要配置 Environment 变量以使其指向 。
GIT_SSHplink.exe使用 SSH 进行身份验证
如果要使用 SSH 协议,需要在 Unity 外部设置 SSH Keys。有关为指定主机设置 Authentication ON 的更多信息,请参阅 Bitbucket、GitLab 和 GitHub 的帮助页面。
使用文件协议
包管理器无法将带有 前缀的 Git URL 识别为 Git 依赖项,除非格式正确。这意味着必须使用 协议或带有 协议的 后缀:
file: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" }}
包管理器将 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+扩展语法
您可以将扩展语法与 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 | |
| 指定的BRANCH | |
| 指定的标签 | |
| 提交哈希 | |
在代码仓库的子文件夹中指定包
如果使用 Git URL 语法指定代码代码仓库,包管理器 会假定包必须位于代码代码仓库的根目录。但是,有些包并不位于其代码仓库的根关卡,有些代码Repositories包含多个包。
您可以使用 Git 网址中的 查询参数通知包管理器查找包的位置。指定的路径必须相对于代码仓库的根,并且指定的子文件夹必须包含包清单( 文件)。
pathpackage.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 协议指定路径和修订版本。但是,查询参数始终位于修订 Anchor 之前。相反 Order 失败。以下是要使用的正确 Order 的示例:
path{ "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:
- 有关 HTTPS Authentication 的信息,请参阅使用 HTTP/HTTPS 协议。
- 有关 SSH Authentication 的信息,请参阅使用 SSH 协议。
如果Users需要Authentication并且没有具有访问远程代码代码仓库权限的有效凭据,则检索存储ON LFS Server上的文件会失败。
包作者可以通过在代码仓库中的 配置文件中提供网址来帮助 Git LFS 客户端找到 LFS Server。有两种方法可以做到这一点:
.lfsconfig# 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.npmignoreGit LFS 缓存
从 Unity 2021.2 开始,可以选择启用 Git LFS 缓存供包管理器在签出基于 Git 的依赖项时使用。这样可以避免时间检查代码仓库都Download相同的文件。
包管理器的 Git LFS 缓存与 Git 代码仓库 Folder 中的 Git LFS 缓存不同。包管理器 无法使用默认的 Git 缓存,因为它在将包复制到Project缓存后不会保持克隆的代码Repositories。
.git/lfs要为 包管理器 Enable Git LFS 缓存,请选择以下选项之一:
- 要启用 Git LFS 缓存并使用默认全局缓存根下的 子文件夹作为其位置,请将
git-lfsEnvironment 变量设置为 Any(非空)值。UPM_ENABLE_GIT_LFS_CACHE - 要启用 Git LFS 缓存并为其使用自定义位置,请将 Environment 变量设置为自定义路径。设置位置When,会自动已启用 Git LFS 缓存选项。
UPM_GIT_LFS_CACHE_PATH
有关为全局缓存设置 Environment 变量的更多信息,请参阅自定义全局缓存。
- 在多个个Projects的依赖关系中使用不同的 Git 修订版
- 经常将包更新为包含不同已更改 LFS 文件的修订版本