---
title: Git 依赖关系简介
product: Unity Editor
version: '6000.0'
latest_version: '7000.0'
status: This page documents version 6000.0. The latest version is 7000.0.
canonical: https://docs.unity.com/zh-cn/engine/6000.0/manual/packages-list/upm-git
latest_url: https://docs.unity.com/zh-cn/engine/7000.0/manual/packages-list/upm-git.md
last_updated: 2026-10-30
generated_at: 2026-11-18T10:42:12.334Z
locale: zh-cn
---

# Git 依赖关系简介

> 了解从 Git 代码仓库获取包产生的依赖关系。了解使用于从 Git 代码仓库获取包的协议和扩展语法。

包管理器 从 Git 代码仓库获取包When，会将包添加到Project的本地。这允许您测试未发布的更改，但无法将使用于为该 Git 代码仓库做出贡献。要将现有的本地 Git 代码仓库设置为 Project 中的依赖关系，请改用本地 Git 代码仓库的[路径](/engine/6000.0/manual/packages-list/dependencies-lp/upm-localpath.md)。

> **Note:**
>
> 无法在[包。json](/engine/6000.0/manual/packages-list/cus-pkg-development/upm-manifest-pkg.md)文件中指定 Git 依赖关系，因为包管理器不支持包之间的 Git 依赖关系。它仅支持 Project 的 Git 依赖关系，因此只能在项目的 [清单.json](/engine/6000.0/manual/packages-list/managing-packages-manifest/upm-manifest-prj.md) 文件中声明 Git 依赖关系。

> **Tip:**
>
> 如果要将 Git 依赖关系更新到代码仓库中的指定版本（[修订版本](#revision)），请参阅\[锁定的 Git 依赖关系]\(# Git-locks)。

本节包括以下主题：

* [要求](#req)

* [Git URL](#syntax)

  * [使用 HTTP/HTTPS 协议](#Git-HTTPS)
  * [使用 SSH 协议](#Git-SSH)
  * [使用文件协议](#Git-FILE)
  * [使用 Git 协议](#Git-GIT)

* [扩展语法](#extended)

  * [指定 Git 修订版](#revision)
  * [在代码仓库的子文件夹中指定包](#subfolder)
  * [同时指定修订和路径](#paths-and-revisions)

* [锁定的 Git 依赖关系](#git-locks)

* [Git LFS 支持](#git-lfs)

## 要求##requirements

要在项目中使用 Git 依赖项，请确保计算机上安装了 [Git 客户端](https://git-scm.com/)（最低版本 2.14.0），并且已将 Git 可执行文件路径添加到路径 System Environment 变量。

> **Warning:**
>
> Unity 测试了包管理器与 Git 2.14.0 及更高版本配合使用。如果使用低于 2.14.0 的 Git 版本，Unity 不能保证结果。

如果代码仓库使用 [Git LFS](https://git-lfs.github.com/) 跟踪文件，请确保计算机上也安装了 Git LFS 客户端。如果未安装，包管理器[无法检索 ON LFS Server](/engine/6000.0/manual/packages-list/upm-errors.md#git-lfs) 存储的文件，而是签出没有 Any 报错或 Warning 消息的 LFS 指针文件。

您可以使用 包管理器 窗口直接从 Git 代码仓库包如需了解更多信息，请参阅[从 Git 网址安装](/engine/6000.0/manual/packages-list/managing-packages-window/upm-ui-actions/upm-ui-giturl.md)。

## Git URL##git-urls

包管理器支持所有 [Git 协议](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols)，本地文件路径异常除外。要将 Git 网址 指定为依赖关系项，请向Project清单中添加要添加的包的Name（使用 Git 网址，而不是版本数量或本地文件路径）。例如，下面演示了如何使用不同的协议指定远程 Git：

```lang-json
{
  "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",
    等等。
  }
}
```

包管理器通过在代码仓库路径结束时查找`.git`文件扩展名来识别网址格式的依赖关系是 Git 网址。某些 Git 代码仓库管Services不Support具有此扩展名的 URL，而Others服务会强制执行此扩展名。因此，如果使用 [Git 协议](#Git-GIT)，或者在 [HTTP/HTTPS](#Git-HTTPS)、[SSH](#Git-SSH) 或[文件](#Git-FILE)网址中添加特殊`git+`前缀，Git 依赖关系语法允许您省略扩展。

> **Note:**
>
> `git+` 前缀是`manifest.json`文件中的特殊标记，指示依赖关系基于 Git。包管理器 在克隆代码仓库When不会将通道 Git。

有关 Git 支持的 URL Format 的更多信息，请参阅 Git [clone](https://git-scm.com/docs/git-clone#_git_urls_a_id_urls_a) 命令的文档。有关 Git 使用的协议之间的区别的 Overview，请参阅[ Git 使用协议](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols)文档。

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

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

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

  有关更多信息，请参阅[在子文件夹中](#subfolder)指定包。

* 您可以指定 Git 修订版，它可以是标签、BRANCHName或要锁定的指定的提交哈希。这样可以确保包管理器始终加载该确切的修订版本。如果未指定修订版本，包管理器 会在默认BRANCH和最新提交位置克隆代码代码仓库，并锁定到该修订版本。例如，字符串`#v2.0.0`于：

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

  有关更多信息，请参阅[指定 Git 修订版本](#revision)。

### 使用 HTTP/HTTPS 协议##using-the-http/https-protocol

您可以使用带有完整网址的 HTTPS 协议：

```lang-json
{
  "dependencies": {
    "com.mycompany.mypackage": "https://github.example.com/myuser/myrepository.git"
  }
}
```

如果您的 Git Server 不支持 `.git` 扩展，则可以添加特殊 `git+` 前缀（无论是否包含扩展）：

```lang-json
{
  "dependencies": {
    "com.mycompany.mypackage1": "git+https://github.example.com/myuser/myrepository1.git",
    "com.mycompany.mypackage2": "git+https://github.example.com/myuser/myrepository2"
  }
}
```

> **Note:**
>
> 或者，可以使用 Git 协议而不是`git+`前缀。有关更多信息，请参阅\[使用 Git 协议]\(# Git-Git)。

如果代码代码仓库可供公众访问，则 HTTPS 是与Users共享 Git URL 的推荐方案，因为您可以直接从 Git 代码仓库管服务Page复制和粘贴 网址。


**Copy the URL from the package repository:**
![](/api/media?file=/engine/6000.0/media/images/upm-git-cloning.png)

如果代码仓库不可公开访问并且您正在使用 HTTPS，则代码仓库 Server 无法对您进行身份验证，因为您无法与 Server 交互以提供凭据。在这种情况下，Editor 会通知您身份Authenticationfailed。

要解决这些 Authentication 问题，您可以：

* 使用 [Git 凭据辅助](https://git-scm.com/docs/gitcredentials)程序预先进行身份验证。有关更多信息，请参阅将 private Repositories 与 HTTPS Git URL [结合使用](/engine/6000.0/manual/packages-list/upm-git/upm-config-https-git.md)。
* 改用 [SSH 协议](#Git-SSH)。如果您使用 Git 代码仓库托管服务设置和配置了 SSH 密钥对，则包管理器可以代表您无缝验证请求。

### 使用 SSH 协议##using-the-ssh-protocol

您可以使用 SSH 协议以及完整的网址：

```lang-json
{
  "dependencies": {
    "com.mycompany.mypackage": "ssh://git@mycompany.github.com/gitproject/com.mycompany.mypackage.git"
  }
}
```

如果您的 Git Server 不支持 `.git` 扩展，则可以添加特殊 `git+` 前缀（无论是否包含扩展）：

```lang-json
{
  "dependencies": {
    "com.mycompany.mypackage1": "git+ssh://git@github.example.com/myuser/myrepository1.git",
    "com.mycompany.mypackage2": "git+ssh://git@github.example.com/myuser/myrepository2"
  }
}
```

> **Note:**
>
> 或者，可以使用 Git 协议而不是`git+`前缀。有关更多信息，请参阅\[使用 Git 协议]\(# Git-Git)。

还可以使用 SCP 类速记，包管理器始终将其识别为 Git 依赖关系：

```lang-json
{
  "dependencies": {
    "com.mycompany.mypackage": "git@mycompany.github.com:gitproject/com.mycompany.mypackage.git"
  }
}
```

#### ON Windows 使用 PuTTY##using-putty-on-windows

使用 SSH 进行身份验证When，Git 位置但是，如果将 [PuTTY](https://www.putty.org/) 用作 ON Windows 的 SSH 客户端，则需要配置 `GIT_SSH` Environment 变量以使其指向 `plink.exe`。

#### 使用 SSH 进行身份验证##authenticating-with-ssh

如果要使用 SSH 协议，需要在 Unity 外部设置 SSH Keys。有关为指定主机设置 Authentication ON 的更多信息，请参阅 [Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/set-up-an-ssh-key/)、[GitLab](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) 和 [GitHub](https://github.com/settings/tokens) 的帮助页面。

> **Note:**
>
> 如果您使用密码短语加密了 SSH 密钥，包管理器 无法检索包，因为它没有提供在Terminal或命令线进入密码短语的方法。在这种情况下，Editor 会通知您身份Authenticationfailed。有关使用 Authentication Agent 的信息，请参阅[将受密码短语保护的 SSH Keys 与 SSH Git URL 结合使用](/engine/6000.0/manual/packages-list/upm-git/upm-config-ssh-git.md)。有关使用 **SSH Agent** 进行 Authentication 的其他信息，请参阅[SSH 解决方案](/engine/6000.0/manual/packages-list/upm-errors.md#ssh-add)。

### 使用文件协议##using-the-file-protocol

包管理器无法将带有 `file:` 前缀的 Git URL 识别为 Git 依赖项，除非格式正确。这意味着必须使用 `git+file:` 协议或带有 `file:` 协议的 `.git` 后缀：

```lang-json
{
  "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"
  }
}
```

> **Note:**
>
> 或者，可以使用 Git 协议而不是`git+`前缀。有关更多信息，请参阅\[使用 Git 协议]\(# Git-Git)。

包管理器将 Any Other 语法解释为[本地路径](/engine/6000.0/manual/packages-list/dependencies-lp/upm-localpath.md)。

### 使用 Git 协议##using-the-git-protocol

包管理器识别`git:`协议，无论是否带有`.git`路径后缀：

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

Git 协议不需要或支持`git+`前缀。

## 扩展语法##extended-syntax

可以使用扩展语法来标识[指定 Git 修订版本](#revision)、[子文件夹中](#subfolder)的包或[两者](#paths-and-revisions)。

您可以将扩展语法与 Unity 支持的Any Git 协议结合使用。

### 指定 Git 修订版##specifying-a-git-revision

要声明要包管理器克隆的指定修订版本，请在网址末尾添加以数量符号 (`#`) 为前缀的修订版本：

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

修订版可以是 Any 标签、BRANCH 或提交哈希。您必须提供完整的提交哈希。Unity 不Support缩短 SHA-1 哈希。表显示了用于指定修订版的示例：

| **语法**    | 'Url'（示例：\*\*\*\*）                                                                              |
| --------- | ----------------------------------------------------------------------------------------------- |
| 默认BRANCH  | `"https://github.example.com/myuser/myrepository.git"`                                          |
| 指定的BRANCH | `"https://github.example.com/myuser/myrepository.git#my-branch"`                                |
| 指定的标签     | `"https://github.example.com/myuser/myrepository.git#tag-pointing-to-package-version"`          |
| 提交哈希      | `"https://github.example.com/myuser/myrepository.git#9e72f9d5a6a3dadc38d813d8399e1b0e86781a49"` |

### 在代码仓库的子文件夹中指定包##specifying-a-package-in-a-subfolder-of-the-repository

如果使用 Git URL 语法指定代码代码仓库，包管理器 会假定包必须位于代码代码仓库的根目录。但是，有些包并不位于其代码仓库的根关卡，有些代码Repositories包含多个包。

您可以使用 Git 网址中的 `path` 查询参数通知包管理器查找包的位置。指定的路径必须相对于代码仓库的根，并且指定的子文件夹必须包含包清单（`package.json` 文件）。

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

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

在这种情况下，包管理器 会注册位于指定代码代码仓库文件夹中的包，并忽略代码代码仓库的REST部分。

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

```lang-json
{
  "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"
  }
}
```

> **Note:**
>
> 如果多个次指定同一代码仓库，包管理器 会多个次克隆同一代码代码仓库，从而导致性能下降和额外的网络使用量。

### 同时指定修订版本和路径##specifying-revisions-and-paths-at-the-same-time

您可以使用 Unity 支持的Any Git 协议指定路径和修订版本。但是，`path`查询参数始终位于修订 Anchor 之前。相反 Order 失败。以下是要使用的正确 Order 的示例：

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

## 锁定的 Git 依赖项##locked-git-dependencies

包管理器的核心原则之一是确定性。如果与其他 Users 共享 Project，则包管理器应安装相同设置的包依赖关系和版本，其中包括从 Git 获取的包。为了实现这一点，包管理器使用[锁定文件](/engine/6000.0/manual/packages-list/dependencies-lp/upm-conflicts-auto.md)跟踪 Git 依赖项的提交哈希。

添加修订版设置为BRANCH或标签的 Git 依赖关系When，包管理器 会获取相应的提交哈希以存储在锁定文件中。随着时间的推移，分支和标签可以点 Git 代码仓库ON的不同提交。例如，BRANCH 可以向其中添加较新的提交。

要将包更新为 BRANCH 或标签指向的不同提交，请使用 [安装包 from Git URL](/engine/6000.0/manual/packages-list/managing-packages-window/upm-ui-actions/upm-ui-giturl.md) 按钮并进入 Git URL。您可以使用相同的 Git 网址，因为 包管理器 会在您提交新建请求When忽略锁定的提交哈希。但是，也可以指定新建修订号、标签或 BRANCH 作为[修订](#revision)版本。

或者，也可以使用 [Client 添加](/engine/6000.0/script-reference/unityeditor/packagemanager/client/add.md)带有该 Git 网址的 C# API 方法。

## Git LFS 支持##git-lfs-support

包管理器支持使用 [Git 大文件存储 (LFS)](https://git-lfs.com/) 的 Repositories 中的 Git 依赖关系。但是，由于 Unity 使用浅克隆，因此并不总是能够正确获取 LFS 跟踪的文件。有时，包可能会导入 Placeholder 指针文件，而不是实际文件内容。有关更多信息，请参阅 [Git LFS 错误](/engine/6000.0/manual/packages-list/upm-errors.md#lfs-errors)。

由于 Git LFS 旨在以最少的配置开销工作，因此它同时支持 HTTPS 和 SSH Authentication：

* 有关 HTTPS Authentication 的信息，请参阅[使用 HTTP/HTTPS 协议](#Git-HTTPS)。
* 有关 SSH Authentication 的信息，请参阅[使用 SSH 协议](#Git-SSH)。

如果Users需要Authentication并且没有具有访问远程代码代码仓库权限的有效凭据，则检索存储ON LFS Server上的文件会失败。

包作者可以通过在代码仓库中的 `.lfsconfig` 配置文件中提供网址来帮助 Git LFS 客户端找到 LFS Server。有两种方法可以做到这一点：

```lang-json
# Option 1: global setting##option-1:-global-setting
[lfs]
  url = ssh://git@HOSTNAME/path/to/repo.git

# Option 2: per-remote setting##option-2:-per-remote-setting
[remote "origin"]
  lfsurl = ssh://git@HOSTNAME/path/to/repo.git
```

如果代码仓库包含`.lfsconfig`文件，请确保将其包含在`.npmignore`文件中，以免将其包含在包的已发布版本中。

### Git LFS 缓存##git-lfs-cache

从 Unity 2021.2 开始，可以选择启用 Git LFS 缓存供包管理器在签出基于 Git 的依赖项时使用。这样可以避免时间检查代码仓库都Download相同的文件。

包管理器的 Git LFS 缓存与 Git 代码仓库 `.git/lfs` Folder 中的 Git LFS 缓存不同。包管理器 无法使用默认的 Git 缓存，因为它在将包复制到Project缓存后不会保持克隆的代码Repositories。

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

* 要启用 Git LFS 缓存并使用[默认全局缓存根](/engine/6000.0/manual/packages-list/package-manager-caches/upm-cache.md)下的 `git-lfs` 子文件夹作为其位置，请将 `UPM_ENABLE_GIT_LFS_CACHE` Environment 变量设置为 Any（非空）值。
* 要启用 Git LFS 缓存并为其使用自定义位置，请将 `UPM_GIT_LFS_CACHE_PATH` Environment 变量设置为自定义路径。设置位置When，会自动已启用 Git LFS 缓存选项。

有关为全局缓存设置 Environment 变量的更多信息，请参阅自[定义全局缓存](/engine/6000.0/manual/packages-list/package-manager-caches/upm-config-cache.md)。

> **Note:**
>
> 使用已启用 Git LFS 的When，此优化需要额外的磁盘Space。您需要决定哪个 Git LFS 文件缓存的优点更大，因为前者会占用磁盘Space，但会避免再次下载相同的文件。但是，在某些情况下，如果不重用文件，就无法 make 使用缓存和使用磁盘空间。例如，Git 依赖项可能会解析为引用不同 LFS 跟踪文件内容的修订版本，例如以下情形：

* 在多个个Projects的依赖关系中使用不同的 Git 修订版
* 经常将包更新为包含不同已更改 LFS 文件的修订版本

## 其他资源##additional-resources

* [将 private Repositories 与 HTTPS Git URL 结合使用](/engine/6000.0/manual/packages-list/upm-git/upm-config-https-git.md)
* [将受密码短语保护的 SSH Keys 与 SSH Git URL 结合使用](/engine/6000.0/manual/packages-list/upm-git/upm-config-ssh-git.md)
* [Git 大文件存储 (LFS)](https://git-lfs.github.com/)
* [服务器上的 Git - 协议](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols)
* [从 Git 网址安装](/engine/6000.0/manual/packages-list/managing-packages-window/upm-ui-actions/upm-ui-giturl.md)
