VR 功能集

将私有存储库与 HTTPS Git URL 配合使用

Git 依赖项

当包管理器从 Git 存储库获取包时，它会将包本地添加到您的项目中。这允许你测试未发布的更改，但不能使用它来贡献该 Git 存储库。若要将现有本地 Git 存储库设置为项目中的依赖项，请改用指向本地 Git 存储库的路径。

注意：您无法指定Git 依赖项包管理器直接从 Git 存储库中检索 Git 依赖项，而不是从包注册表中检索 Git 依赖项。Git 依赖项使用 Git URL 引用而不是版本，并且无法保证包的质量、稳定性、有效性，甚至无法保证其package.json文件遵循有关此包的正式发布版本的语义版本控制规则。更多信息
请参阅术语表在package.json文件中，因为包管理器不支持包之间的 Git 依赖项。它仅支持项目的 Git 依赖项，因此您只能在项目的manifest.json文件中声明 Git 依赖项。

提示：如果要将 Git 依赖项更新为存储库中的特定版本（修订版），请参阅锁定的 Git 依赖项。

本节包括以下主题：

要求
Git 网址
扩展语法
锁定的 Git 依赖项
Git LFS 支持

要求

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

警告：Unity 测试了包管理器是否适用于 Git 2.14.0 及更高版本。如果您使用低于 2.14.0 的 Git 版本，Unity 无法保证结果。

如果存储库使用 Git LFS 跟踪文件，请确保您的计算机上也安装了 Git LFS 客户端。如果未安装，包管理器将无法检索存储在 LFS 服务器上的文件，而是签出 LFS 指针文件，而不会出现任何错误或警告消息。

您可以使用“包管理器”窗口直接从 Git 存储库安装包。有关更多信息，请参阅从 Git URL 安装。

Git 网址

包管理器支持所有 Git 协议，但本地文件路径除外。若要将 Git URL 指定为依赖项，请使用 Git URL 而不是版本号或本地文件路径添加要添加的包的名称项目清单每个 Unity 项目都有一个项目清单，用作包管理器的入口点。此文件必须在<project>/Packages目录。包管理器使用它来配置许多内容，包括该项目的依赖项列表，以及要查询包的任何包存储库。更多信息
请参阅术语表.例如，这演示了如何使用不同的协议指定远程 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.
  }
}

包管理器通过查找.git文件扩展名。某些 Git 存储库托管服务不支持具有此扩展的 URL，而其他服务则强制执行它。因此，如果您使用 GIT 协议，或者如果您添加特殊的git+前缀添加到 HTTP/HTTPS、SSH 或 FILE URL 中。

注意：这git+prefix 是manifest.json文件，指示依赖项基于 Git。克隆存储库时，包管理器不会将其传递给 Git。

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

还可以对 Git 依赖项使用扩展语法：

如果所需的包不在存储库的根目录中，则可以指定存储库中包子文件夹的路径。仅当所需的包不在存储库的根目录时，才需要这样做。例如，字符串?path=/folder1/folder2在：

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

有关更多信息，请参阅在子文件夹中指定包。
您可以指定 Git 修订版，它可以是标签、分支名称或要锁定的特定提交哈希。这可确保包管理器始终加载该确切的修订版。如果未指定修订版，包管理器会在默认分支和最新提交处克隆存储库，并锁定该修订版。例如，字符串#v2.0.0在：

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

有关更多信息，请参阅指定 Git 修订版。

使用 HTTP/HTTPS 协议

您可以将 HTTPS 协议与完整 URL 一起使用：

{
  "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 凭据帮助程序预先进行身份验证。有关更多信息，请参阅将私有存储库与 HTTPS Git URL 一起使用。
请改用 SSH 协议。如果使用 Git 存储库托管服务设置和配置 SSH 密钥对，则包管理器可以代表您无缝地对请求进行身份验证。

使用 SSH 协议

您可以将 SSH 协议与完整 URL 一起使用：

{
  "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 的简写，包管理器始终将其识别为 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 密钥，则包管理器无法检索包，因为它不提供在终端或命令行中输入密码的方法。在这种情况下，编辑器会通知你身份验证失败。有关使用身份验证代理的信息，请参阅将受密码保护的 SSH 密钥与 SSH Git URL 配合使用。有关使用 ssh-agent 进行身份验证的其他信息，请参阅 SSH 解决方案。

使用 FILE 协议

包管理器无法识别具有file:prefix 作为 Git 依赖项，除非它们格式正确。这意味着您必须使用git+file:协议或.git后缀加上file:协议：

{
  "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:协议，无论是否带有.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 支持的任何 Git 协议一起使用。

指定 Git 修订版

要声明您希望包管理器克隆的特定修订版，请在 URL 末尾添加以数字符号（）为前缀的修订版：#

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

修订版可以是任何标签、分支或提交哈希。您必须提供完整的提交哈希值。Unity 不支持缩短的 SHA-1 哈希值。下表显示了指定修订的示例：

语法	网址示例
最新的默认分支	`"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 语法指定存储库，则包管理器会假定该包必须位于存储库的根目录下。但是，某些包不位于其存储库的根级别，并且某些存储库包含多个包。

您可以使用pathquery 参数来通知包管理器在哪里可以找到包。您指定的路径必须相对于存储库的根目录，并且您指定的子文件夹必须包含包清单每个包都有一个清单，该清单向包管理器提供有关包的信息。清单包含包的名称、版本、用户说明、对其他包的依赖关系（如果有）以及其他详细信息等信息。更多信息
请参阅术语表 (package.json文件）。

要为 Git 依赖项指定存储库子文件夹，请使用path查询参数：

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

在这种情况下，包管理器将注册位于指定存储库子文件夹中的包，并忽略存储库的其余部分。

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

{
  "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 支持的任何 Git 协议指定路径和修订版。但是，pathquery 参数始终位于修订锚点之前。相反的顺序失败。这是正确使用顺序的示例：

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

锁定的 Git 依赖项

包管理器的核心原则之一是确定性。如果您与其他用户共享您的项目，包管理器应安装同一组包依赖项和版本，其中包括它从 Git 获取的包。为了实现这一点，包管理器使用锁定文件跟踪 Git 依赖项的提交哈希。

当您添加修订设置为分支或标记的 Git 依赖项时，包管理器会获取相应的提交哈希以存储在锁文件中。随着时间的推移，分支和标记可以指向 Git 存储库上的不同提交。例如，分支可以向其添加较新的提交。

若要将包更新为分支或标记指向的其他提交，请使用 “从 git URL 安装包”按钮并输入 Git URL。您可以使用相同的 Git URL，因为当您提交新请求时，包管理器会忽略锁定的提交哈希。但是，您也可以将新的修订版本号、标记或分支指定为修订版本。

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

Git LFS 支持

包管理器支持使用 Git LFS 的存储库的 Git 依赖项。由于 Git LFS 旨在以最小的配置开销工作，因此它支持 HTTPS 和 SSH 身份验证：

有关HTTPS认证的信息，请参阅使用HTTP/HTTPS协议。
有关 SSH 身份验证的信息，请参阅使用 SSH 协议。

如果用户需要身份验证并且没有访问远程存储库的有效凭据，则检索存储在 LFS 服务器上的文件将失败。

包作者可以通过在.lfsconfig配置文件。有两种方法可以做到这一点：

# 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 缓存

从 Unity 2021.2 开始，您可以选择启用 Git LFS 缓存，供包管理器在签出基于 Git 的依赖项时使用。这样可以避免每次签出存储库的不同版本时都必须下载相同的文件。

包管理器的 Git LFS 缓存与.git/lfs文件夹。包管理器不能使用默认的 Git 缓存，因为它在将包复制到项目缓存后不会保留克隆的存储库。

要为包管理器启用 Git LFS 缓存，请选择以下选项之一：

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

其他资源

VR 功能集

将私有存储库与 HTTPS Git URL 配合使用

手册

Git 依赖项

要求

Git 网址

使用 HTTP/HTTPS 协议

使用 SSH 协议

在 Windows 上使用 PuTTY

使用 SSH 进行身份验证

使用 FILE 协议

使用 GIT 协议

扩展语法

指定 Git 修订版

在存储库的子文件夹中指定包

同时指定修订和路径

锁定的 Git 依赖项

Git LFS 支持

Git LFS 缓存

其他资源