Git 依赖关系

When the Package Manager fetches a package from a Git repository, it adds the package locally to your project. This allows you to test unpublished changes, but you can’t use it to contribute to that Git repository. To set up an existing local Git repository as a dependency in your project, use a path to your local Git repository instead.

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

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

此部分包含以下主题：

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

要求

To use Git dependencies in a project, make sure you installed the Git client (minimum version 2.14.0) on your computer and that you have added the Git executable path to the PATH system environment variable.

Warning: Unity tested the Package Manager to work with Git 2.14.0 and above. Unity can’t guarantee the results if you use Git versions below 2.14.0.

If the repository tracks files with Git LFS, make sure the Git LFS client is also installed on your machine. If it’s not installed, the Package Manager can’t retrieve the files stored on the LFS server and instead checks out the LFS pointer files without any error or warning messages.

可以使用 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.
  }
}

The Package Manager recognizes that a dependency formatted as a URL is a Git URL by looking for the .git file extension at the end of the repository path. Some Git repository hosting services don’t support URLs with this extension while others enforce it. For this reason, the Git dependency syntax allows you to omit the extension if you use the GIT protocol, or if you add a special git+ prefix to the HTTP/HTTPS, SSH, or FILE URL.

Note: The git+ prefix is a special marker in the manifest.json file that indicates that the dependency is Git based. The Package Manages doesn’t pass it to Git when cloning the repository.

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

You can also use extended syntax for Git dependencies:

• If the package you want isn’t at the root of the repository, you can specify a path to a package’s subfolder in the repository. This is necessary only if the package you want isn’t at the root of the repository. For example, the string ?path=/folder1/folder2 in:

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

If your Git server doesn’t support the .git extension, you can add the special git+ prefix, with or without the extension:

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

If the repository isn’t publicly accessible and you are using HTTPS, the repository server fails to authenticate you because you can’t interact with the server to provide your credentials. In this case, the Editor notifies you that authentication failed.

To work around these authentication issues, you can either use a Git credentials helper to authenticate beforehand, or use the SSH protocol instead. If you set up and configure an SSH key pair with the Git repository hosting service, the Package Manager can authenticate the request seamlessly on your behalf.

使用 SSH 协议

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

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

If your Git server doesn’t support the .git extension, you can add the special git+ prefix, with or without the extension:

{
  "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 协议

The Package Manager doesn’t recognize Git URLs with the file: prefix as Git dependencies unless they’re properly formatted. This means you must use either the git+file: protocol, or the .git suffix with the file: protocol:

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

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

If you specify a repository using the Git URL syntax, the Package Manager assumes that the package must be at the root of the repository. However, some packages aren’t located at the root level of their repository, and some repositories contain more than one package.

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

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

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

In this case, the Package Manager registers the package located in the specified repository subfolder and disregards the rest of the repository.

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

{
  "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 依赖关系

One of the core principles of the Package Manager is determinism. If you share your project with other users, the Package Manager should install the same set of package dependencies and versions, and that includes packages that it fetches from Git. To achieve this, the Package Manager tracks commit hashes of Git dependencies by using a lock file.

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

To update the package to a different commit that a branch or tag points to, use the Install 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 支持

The Package Manager supports Git dependencies with repositories using Git LFS. Since Git LFS is designed to work with minimal configuration overhead, it supports both HTTPS and SSH authentication:

• For information about HTTPS authentication, see Using the HTTP/HTTPS protocol.
• For information about SSH authentication, see Using the SSH protocol.

Retrieval of files stored on the LFS server fails if users need authentication and don’t have valid credentials with permission to access the remote repository.

包作者可以通过在代码仓库中的 .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 it copies packages 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 Customize the global cache location.

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 you from downloading the same files again. However, some situations can’t make use of the cache and use up disk space without reusing the files. For example, your Git dependencies might resolve to revisions that reference different LFS-tracked file content, such as these scenarios:

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

其他资源

• Git Large File Storage (LFS)
• Git on the Server - The Protocols
• Installing from a Git URL