Git 依赖关系

当 Package Manager 从 Git 代码仓库获取包时，会将包添加到项目本地。这使您可以轻松测试未发布的更改，但不能将对包的更改合并到该 Git 代码仓库。要将现有的本地 Git 代码仓库设置为项目中的依赖关系，请改用本地 Git 代码仓库路径。

不能在 package.json 文件中指定 Git 依赖关系，因为 Package Manager 不支持包之间的 Git 依赖关系。它只支持项目的 Git 依赖关系，所以只能在项目的 manifest.json 文件中声明 Git 依赖关系。

提示：如果要从代码仓库将 Git 依赖关系更新到特定版本（修订版本），请参阅已锁定的 Git 依赖关系。

此部分包含以下主题：

• 要求
• Git URL 和扩展语法
  • 使用 HTTP/HTTPS 协议
  • 使用 SSH 协议
  • 使用 FILE 协议
  • 使用 GIT 协议
  • 以特定修订版本为目标
    • 在代码仓库的子文件夹中指定包
    • 同时使用路径和修订版本
  • 在子文件夹中指定包
• 已锁定的 Git 依赖关系
• Git LFS 支持

要求

要在项目中使用 Git 依赖关系，请确保您的计算机上安装了 Git 客户端（最低版本 2.14.0），并且已将 Git 可执行路径添加到 PATH 系统环境变量中。

警告：Package Manager 已经过测试，可与 Git 2.14.0 及更高版本配合使用。如果您使用低于 2.14.0 的 Git 版本，Unity 无法保证结果。

如果代码仓库使用 Git LFS 来跟踪文件，请确保您的计算机上还安装了 Git LFS 客户端。如果未安装，则 Package Manager 无法获取存储在 LFS 服务器上的文件，而是签出 LFS 指针文件，并且不会显示任何错误或警告消息。

可以使用 Package Manager 窗口直接从 Git 代码仓库安装包。有关更多信息，请参阅从 Git URL 安装。

Git URL 和扩展语法

Package Manager 支持所有 Git 协议（直接文件路径除外）。要将 Git URL 指定为依赖关系，请添加要使用 Git URL 添加的包名称，而不是版本号或本地文件路径。例如，下面演示了如何使用不同协议指定远程 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",
    etc.
  }
}

Package Manager 通过查找代码仓库路径末尾的 .git 文件扩展名，来识别格式为 URL 的依赖关系是 Git URL。一些 Git 代码仓库托管服务不支持具有此扩展名的 URL，而其他服务则强制执行它。因此，如果您使用 GIT 协议，或是如果将特殊 git+ 前缀添加到 HTTP/HTTPS、SSH 或 FILE URL，则 Git 依赖关系语法允许您省略扩展名。

注意：git+ 前缀是 manifest.json 文件中的特殊标记，指示依赖关系基于 Git。Package Manager 不会在克隆代码仓库时将它传递给 Git。

有关 Git 支持的 URL 格式的更多信息，请参阅适用于 git clone 命令的文档。有关 Git 使用的各种协议之间的差异概述，请参阅有关使用协议的 Git 文档。

此外，Git 依赖关系使用一种扩展语法：

• 如果所需的包不在代码仓库的根目录中，则可以指定代码仓库中放置该包的子文件夹的路径。仅当所需的包不在代码仓库的根目录中时才需要这样做。例如，以下内容中的字符串 ?path=/folder1/folder2：

  "https://github.example.com/myuser/myrepository.git?path=/folder1/folder2"。

  有关更多信息，请参阅在子文件夹中指定包。

• 可以指定 Git 修订版本，它可以是标签、分支名称或是要锁定到的特定提交哈希。这可确保 Package Manager 始终加载准确的修订版本。如果未指定修订版本，则 Package Manager 会在默认分支和最新提交处克隆代码仓库。例如，以下内容中的字符串 #v2.0.0：

  "https://github.example.com/myuser/myrepository.git#v2.0.0"

  有关更多信息，请参阅以特定修订版本为目标。

使用 HTTP/HTTPS 协议

可以使用带有完整 URL 的 HTTPS 协议：

{
  "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 凭据帮助程序提前进行身份验证，或是改为使用 SSH 协议。如果您使用 Git 代码仓库托管服务设置和配置 SSH 密钥对，则 Package Manager 可以代表您对请求进行无缝身份验证。

使用 SSH 协议

可以使用带有完整 URL 的 SSH 协议：

{
  "dependencies": {
    "com.mycompany.mypackage": "ssh://git@mycompany.github.com/gitproject/com.mycompany.mypackage.git"
  }
}

如果 Git 服务器不支持 .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 协议。

还可以使用类似 SCP 的速记，Package Manager 会始终将它识别为 Git 依赖关系：

{
  "dependencies": {
    "com.mycompany.mypackage": "git@mycompany.github.com:gitproject/com.mycompany.mypackage.git"
  }
}

在 Windows 上使用 PuTTY

当您使用 SSH 进行身份验证时，Git 会使用默认位置的密钥。但是，如果您在 Windows 上使用 PuTTY 作为 SSH 客户端，则需要配置 GIT_SSH 环境变量以使其指向 plink.exe。

使用 SSH 进行身份验证

如果要使用 SSH 协议，则需要在 Unity 外部设置 SSH 密钥。有关为特定主机设置身份验证的更多信息，请参阅 Bitbucket、GitLab 和 GitHub 的帮助页面。

注意：如果您使用口令短语对 SSH 密钥进行加密，则 Package Manager 无法获取包，因为它未提供用于在终端或命令行中输入口令短语的方式。在这种情况下，编辑器会通知您身份验证失败。有关使用 ssh-agent 进行身份验证的帮助，请参阅适用于 SSH 的解决方案。

使用 FILE 协议

除非格式正确，否则 Package Manager 不会将带有 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 协议。

相反，Package Manager 会将任何其他语法解释为本地路径。

使用 GIT 协议

Package Manager 可识别 git: 协议（带或不带 .git 路径后缀）：

{
  "dependencies": {
    "com.mycompany.mypackage1": "git://github.example.com/myuser/myrepository1.git",
    "com.mycompany.mypackage2": "git://github.example.com/myuser/myrepository2"
  }
}

GIT 协议不需要也不支持 git+ 前缀。

定位某个特定修订版本

若要声明希望 Package Manager 克隆的特定修订版本，请在 URL 末尾添加以数字符号 (#) 作为前缀的修订版本：

{
  "dependencies": {
    "com.mycompany.mypackage1": "https://github.example.com/myuser/myrepository1.git#revision",
    "com.mycompany.mypackage2": "git+https://github.example.com/myuser/myrepository2#revision"
  }
}

The revision can be any tag, branch or commit hash. You must provide a full commit hash. Unity doesn’t support shortened SHA–1 hashes. This table shows examples for specifying revisions:

语法：	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 语法指定代码仓库，则 Package Manager 假定包必须位于代码仓库的根目录中。但是，某些包并不位于其代码仓库的根级别，某些代码仓库包含多个包。

可以在 Git URL 中使用 path 查询参数向 Package Manager 通知包的位置。指定的路径必须相对于代码仓库的根目录，并且指定的子文件夹必须包含包清单（package.json 文件）。

若要为 Git 依赖关系指定代码仓库子文件夹，请使用 path 查询参数：

{
  "dependencies": {
    "com.mycompany.mypackage": "https://github.example.com/myuser/myrepository.git?path=/subfolder"
  }
}

在这种情况下，Package Manager 仅注册位于指定代码仓库子文件夹中的包，而忽略代码仓库的其余部分。

有时一个代码仓库包含多个相关包。如果要从同一个代码仓库添加多个包，则必须向项目清单添加两个单独的条目：

{
  "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"
  }
}

注意：如果多次指定同一个代码仓库，则 Package Manager 会多次克隆同一个代码仓库，这会导致性能下降和额外的网络使用。

同时使用路径和修订版本

path 查询参数始终位于修订版本锚点之前。相反顺序会失败。下面是要使用的正确顺序的示例：

{
  "dependencies": {
    "com.mycompany.mypackage": "https://github.example.com/myuser/myrepository.git?path=/example/folder#v1.2.3"
  }
}

已锁定的 Git 依赖关系

Package Manager 的核心原则之一是确定性。如果您与其他用户共享项目，则 Package Manager 应安装相同的包依赖关系和版本集，其中包括它从 Git 获取的包。为了实现此目标，Package Manager 会使用锁定文件，该文件跟踪使用的 Git 依赖关系的提交哈希。

添加修订版本设置为分支或标签的 Git 依赖关系时，Package Manager 会获取相应的提交哈希以存储在锁定文件中。随着时间推移，分支和标签可以指向 Git 代码仓库上的不同提交。例如，一个分支可以添加更新的提交。

若要将包更新到分支或标签指向的不同提交，请使用 Add package from git URL 按钮并输入 Git URL。可以使用相同的 Git URL，因为 Package Manager 会在提交新请求时忽略已锁定的提交哈希。还可以指定一个新的修订号、标签或分支作为修订版本。

或者，可以使用带有该 Git URL 的 Client.Add C# API 方法创建脚本。

Git LFS 支持

Package Manager 使用 Git LFS 支持与代码仓库的 Git 依赖关系。由于 Git LFS 旨在以最少的配置开销工作，因此它同时支持 HTTPS 和 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 缓存

默认情况下，Git LFS 客户端将从 LFS 服务器下载的文件缓存在 Git 代码仓库的 .git/lfs 文件夹中。这样可以在每次签出代码仓库的不同修订版本时，相同的文件不必下载。但是，Package Manager 无法将此缓存用于 Git 依赖项，因为在将包复制到项目缓存后，它不会保留克隆的代码仓库。

从 Unity 2021.2 开始，您可以选择为 Package Manager 启用 Git LFS 缓存，以便在签出基于 Git 的依赖项时使用。

为此，请选择以下选项之一：

• 要启用 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 文件的修订版本

---

• 在 Unity 2019.4 中添加了锁定文件 NewIn20194
• 在 Unity 2019.4 中添加了子文件夹中的 Git 依赖关系 NewIn20194
• 在 Unity 2019.4 中添加了用于 Git 依赖项的 Git LFS 缓存 NewIn20194