Git 依赖关系

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

Note: You cannot specify Git dependencies in a package.json file because the Package Manager does not support Git dependencies between packages. It only supports Git dependencies for projects, so you can only declare Git dependencies in the project’s manifest.json file.

提示：如果要从代码仓库将 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 和扩展语法

The Package Manager supports all Git protocols, with the exception of local file paths. To specify a Git URL as a dependency, add the name of the package to add with a Git URL instead of the version number or local file path to the project manifest. For example, this demonstrates how to specify a remote Git using different protocols:

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

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

• You can specify a Git revision, which can be a tag, branch name, or a specific commit hash to lock onto. This ensures that the Package Manager always loads that exact revision. If you don’t specify a revision, the Package Manager clones the repository at the default branch and latest commit and locks onto that revision. For example, the string #v2.0.0 in:

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

修订版本可以是任何标签、分支或提交哈希。下表显示有关指定修订版本的示例：

语法：	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 代码仓库上的不同提交。例如，一个分支可以添加更新的提交。

To update the package to a different commit that a branch or tag points to, use the Add package from git URL button and enter a Git URL. You can use the same Git URL, because the Package Manager ignores the locked commit hash when you submit a new request. However, you can also specify a new revision number, tag, or branch as a revision instead.

或者，可以使用带有该 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 缓存

As of Unity 2021.2, you can optionally enable a Git LFS cache for the Package Manager to use when checking out Git-based dependencies. This avoids having to download the same file every time you check out a different revision of the repository.

The Git LFS cache for the Package Manager is different from the Git LFS cache in the .git/lfs folder of your Git repository. The Package Manager can’t use the default Git cache because it doesn’t keep cloned repositories after the packages have been copied to the project cache.

To enable the Git LFS cache for the Package Manager, choose one of the following options:

• 要启用 Git LFS 缓存并使用默认全局缓存根下的 git-lfs 子文件夹作为其位置，请将 UPM_ENABLE_GIT_LFS_CACHE 环境变量设置为任何（非空）值。
• 要启用 Git LFS 缓存并为其使用自定义位置，请将 UPM_GIT_LFS_CACHE_PATH 环境变量设置为自定义路径。当您设置位置时，Git LFS 缓存选项会自动启用。

For more information about how to set environment variables for the global cache, see Customizing the shared cache locations.

Note: This optimization requires extra disk space when using Git LFS-enabled packages. You need to decide which is the greater benefit: Git LFS file caching costs disk space but saves on re-downloading the same files. However, some situations can’t make use of the cache and use up disk space without re-using the files. For example, your Git dependencies might resolve to revisions that reference different LFS-tracked file content, such as these scenarios:

• 在多个项目的依赖项中使用不同的 Git 修订版本
• 经常将包更新为包含不同更改的 LFS 文件的修订版本

---

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