Git 依赖关系

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

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

此部分包含以下主题：

• 要求

• Git URL 和扩展语法

  • 使用 HTTP/HTTPS 协议

  • 使用 SSH 协议

  • 使用 FILE 协议

  • 使用 GIT 协议

  • 以特定修订版本为目标

  • 在子文件夹中指定包

• 已锁定的 Git 依赖关系

• Git LFS 支持

要求

To use Git dependencies in a project, make sure the Git client is installed on your machine and that you have added the Git executable path to the PATH system environment variable.

如果代码仓库使用 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。

For more information about the format of Git-supported URLs, see the documentation for the git clone command and Git server protocols.

此外，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。

If the repository is not 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. To work around this, choose one of the following solutions:

• Authenticate beforehand using a Git credentials helper.

• Include your username and password directly in the Git URL.

  Warning: This option is not recommended because it is not secure.

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

如果 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 的帮助页面。

Note: If you encrypted your SSH key with a passphrase, the Package Manager can’t retrieve the package, because it doesn’t provide a way to enter the passphrase in a terminal or command line. In this case, you can either use the HTTPS protocol with a Git credential helper or use Git’s built-in SSH authentication ssh-agent. On Windows, if you are using PuTTY, you can use its Pageant authentication helper.

If you don’t have proper access, the Editor notifies you that authentication failed. For more information, see Authentication issues with Git URLs.

使用 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"

Specifying a package in a subfolder of the repository

如果使用 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 会多次克隆同一个代码仓库，这会导致性能下降和额外的网络使用。

Revisions

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 fetchs from Git. To achieve this, the Package Manager uses a lock file, which tracks which commit hashes of Git dependencies are used. For example, here is an entry in the lock file for a Git dependency:

"com.mycompany.mypackage": {
  "version": "git@github.example.com/myuser/myrepository.git",
  "depth": 0,
  "source": "git",
  "dependencies": {
    "com.unity.package-validation-suite": "0.10.0-preview",
    "com.unity.nuget.newtonsoft-json": "2.0.0-preview"
  },
  "hash": "6758e2800ac87cb37a9a8179610f92844a85cf7b"
},
    etc.

Updating a locked version

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

To force the Package Manager to update the package to the new commit that a branch or tag points to, use one of these methods:

• Manually remove the corresponding package section from the packages-lock.json file. The next time you trigger a package resolution process (for example, when Unity regains application focus), the Package Manager fetches the branch head or tag and then adds it to the lock file.
• Create a script with the Client.Add C# API method with the same Git dependency.

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 文件中，以避免将它包含在包的已发布版本中。

---

• 在 Unity 2019.4 中添加了锁定文件 NewIn20194
• 在 Unity 2019.4 中添加了子文件夹中的 Git 依赖关系 NewIn20194