陈巧倩

Unity中文版-Unity's Package Manager(二)(自翻译)

· 749 words · 4 minutes to read
Categories: Unity
Tags: Document

翻译Unity中文版的初衷是因为官方提供的中文版存在缺陷,而且翻译的不全。现在基于Unity2023.2版本对官方文档进行翻译。

Unity’s Package Manager(二) 🔗

Configuration(配置) 🔗

本节将向您展示如何针对PackageManager进行以下配置:

  • 网络配置:绕过防火墙并设置代理服务器
  • 有范围的注册表身份验证:为需要此项的任何范围内的程序包注册表服务器创建并提供身份验证令牌
  • 定制全局缓存:更改全局缓存文件夹的位置以及注册表数据缓存的最大大小
  • 定制资产商店缓存位置:更改Asset Store程序包缓存文件夹的位置
  • 使用HTTPS Git URLs的私有仓库:使用Git凭证助手访问通过HTTPS进行的私有仓库
  • 使用SSH Git URLs的有密码保护的SSH密钥:使用认证代理访问通过SSH进行的私有仓库

此外,您可以在配置文件下找到PackageManager配置文件的位置。

Configuration files(配置文件) 🔗

PackageManager支持两种配置文件:全局配置文件和用户配置文件。这两种文件都使用TOML格式,并且它们出现在不同的位置:

  • 全局配置文件适用于机器上的所有用户。例如,当为整个机器设置代理服务器时,您可以定义额外的SSL证书机构。
  • 用户配置文件适用于单个用户。例如,您可以设置用于使用有范围的注册表访问的自定义包注册服务器的认证令牌。这些令牌验证了特定的用户账户。

Global configuration file location(全局配置文件位置) 🔗

PackageManager使用名为upmconfig.toml的全局配置文件。安装Unity Hub或Editor时,此文件不会被创建,但如果你需要自定义你的配置,你可以在以下位置创建它:

Environment: Location:
Windows %ALLUSERSPROFILE%\Unity\config\upmconfig.toml (for example, C:\ProgramData\Unity\config\upmconfig.toml)
macOS and Linux /etc/upmconfig.toml

你可以定义一个自定义位置来覆盖你的配置文件的默认位置。要做到这一点,创建一个UPM_GLOBAL_CONFIG_FILE环境变量,并将其值设置为你的配置文件的绝对路径,包括文件名。

User configuration file location(用户配置文件位置) 🔗

PackageManager使用名为.upmconfig.toml的用户配置文件。当你安装Unity Hub或Editor时,该文件并不被创建,但如果你需要自定义你的配置,你可以在下列位置创建它:

Environment: Location:
Windows (user account) %USERPROFILE%\.upmconfig.toml (for example, C:\Users\myusername\.upmconfig.toml)
Windows (system user account) %ALLUSERSPROFILE%\Unity\config\ServiceAccounts\.upmconfig.toml (for example, C:\Users\Public\Unity\config\ServiceAccounts\.upmconfig.toml)
macOS and Linux ~/.upmconfig.toml (for example, /Users/myusername/.upmconfig.toml)

你可以定义一个自定义位置来覆盖你的配置文件的默认位置。要做到这一点,创建一个UPM_USER_CONFIG_FILE环境变量,并将其值设置为你的配置文件的绝对路径,包括文件名。

Solving network issues(解决网络问题) 🔗

使用以下步骤来:

  • 配置你的防火墙设置,使Unity可以访问PackageManager注册服务器。
  • 配置代理服务器,可以通过设置环境变量或添加自定义证书颁发机构(CA)证书来实现。

Configuring your firewall(配置你的防火墙) 🔗

为确保Unity的PackageManager可以访问其使用的域名,你必须将这些域名添加到防火墙的安全列表。

关于这些域名的完整列表,以及Unity编辑器所需的所有域名,请参考Unity应用程序可以访问的终端点。你可以使用列表添加整个域名,或使用表格选择性地添加子域名。

请参考你的操作系统的帮助,了解如何将域名添加到防火墙的安全列表。

Configuring your proxy server(配置你的代理服务器) 🔗

当使用代理服务器时,配置HTTP_PROXYHTTPS_PROXY环境变量,供Unity的PackageManager在对Unity包注册表执行请求时使用。更多信息,请参考使用环境变量来识别你的代理服务器。

你可以根据你的操作系统,全局设置这些变量(系统变量或用户变量)。或者,你也可以创建一个命令文件来设置这些环境变量并启动Hub。

对于你在一个使用PackageManager不识别的证书的代理服务器后面的环境,你可以配置一个自定义证书颁发机构。

Custom certificate authority(自定义证书颁发机构) 🔗

在一些组织中,用户只能通过代理服务器访问互联网。一些代理会解开HTTPS内容,然后用他们自己的SSL证书重新打包。Unity包管理器的底层HTTPS层有时会拒绝这些证书,因为它不认可发出这些证书的证书颁发机构。当这种情况发生时,PackageManager会将连接视为可能的中间人攻击(MITM)。这意味着,除非你配置额外的SSL证书颁发机构来允许这些证书,否则你无法使用Unity中的许多功能,包括PackageManager。

要配置额外的SSL证书颁发机构:

  1. 定位upmconfig.toml全局配置文件。如果文件不存在,创建一个空的文本文件。

  2. 创建一个包含一个或多个自定义证书颁发机构的证书的文本文件。文件必须由一个或多个受信任的证书组成,证书格式为Privacy-Enhanced Mail (PEM)。例如:

    -----BEGIN CERTIFICATE-----
    MIIC+zCCAeOgAwIBAgIJAO0U6hVJnbvjMA0GCSqGSIb3DQEBBQUAMBQxEjAQBgNV
    BAMMCWxvY2FsaG9zdDAeFw0xOTAzMTIwMTIxMzRaFw0yOTAzMDkwMTIxMzRaMBQx
    (additional lines omitted for conciseness)
    LFwHSUdqk0lJK4b0mCwyTHNvYO1IDziE5EKwfuaKVgOa62iCHVahgIVa+een4EfS
    hCCr3M3cq11Mi+mnRi1scxxrOno4OEEChWg2szZLlxBrkVJllrrq620XJ6RLB/8=
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    MIIDtzCCAp+gAwIBAgIQDOfg5RfYRv6P5WD8G/AwOTANBgkqhkiG9w0BAQUFADBl
    MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3
    (additional lines omitted for conciseness)
    H2sMNgcWfzd8qVttevESRmCD1ycEvkvOl77DZypoEd+A5wwzZr8TDRRu838fYxAe
    +o0bJW1sj6W3YQGx0qMmoRBxna3iw/nDmVG3KwcIzi7mULKn+gpFL6Lw8g==
    -----END CERTIFICATE-----
    
  3. 如果可能的话,将此文件保存到与全局配置文件相同的文件夹中,虽然Unity支持在文件系统的任何位置。

  4. 在全局配置文件中,添加caFile键,并将其值设置为你的PEM文件的绝对文件路径。重要提示:在TOML文件中设置Windows路径时,使用正斜杠(/)或双反斜杠(\\)。不要使用单反斜杠(\),因为它们是标记转义序列的特殊字符,可能会导致TOML解析错误。

    Windows example

    caFile = "C:\\ProgramData\\Unity\\config\\cert.pem"
    

    macOS and Linux example

    caFile = "/etc/cert.pem"
    

Scoped registry authentication(限定范围的注册表身份验证) 🔗

一些组织在需要身份验证才能访问的私有包注册表上托管他们自己的包。如果你是这些组织的员工或客户,你必须配置一个带有npm身份验证的限定范围的注册表。为了建立这个,获取一个npm身份验证令牌,然后将该令牌添加到你的用户配置文件中。

1) Fetch the npm authentication token(获取npm身份验证令牌) 🔗

创建和访问npm身份验证令牌的过程因每个注册表提供商而异。例如,JFrog的Artifactory仓库管理器生成身份验证令牌的程序与npm不同。这是一个典型程序的例子,但你需要遵循特定包注册表供应商为你的限定范围的注册表推荐的过程。

要从npm获取身份验证令牌:

  1. 在你的计算机上本地安装npm。

  2. 从终端,输入以下命令来登录注册表:

    $ npm login --registry <registry url>

  3. 定位并打开生成的.npmrc文件。

  4. 定位_authToken_auth条目,并复制其值(参阅下面的例子)。

    根据注册表,令牌字符串可以是全局唯一标识符(GUID)、令牌,或者是专有格式的字符串。

Examples of .npmrc files(.npmrc文件的示例) 🔗

这是一个包含_authToken属性的.npmrc文件的例子:

registry=https://example.com:1234/mylocation/
//example.com:1234/mylocation/:_authToken=<AUTH TOKEN>

这是一个包含_auth属性的.npmrc文件的示例:

registry=https://example.com:1234/mylocation
_auth=<AUTH TOKEN>
email=<EMAIL>
always-auth=true

2) Configure authentication information(配置身份验证信息) 🔗

使用npmAuth配置模式在.upmconfig.toml用户配置文件中存储每个需要身份验证的限定范围的注册表的令牌信息。当你把这个信息保存到配置文件后,包管理器会在向文件中的每个注册表发起的每个请求上提供你的身份验证信息。

遵循这些指示将你的身份验证信息添加到用户配置文件中:

  1. 定位.upmconfig.toml用户配置文件。如果文件不存在,创建一个空的文本文件。
  2. 根据你是否使用Bearer(基于令牌)或Basic(Base64加密)的身份验证机制,使用模式格式化你的身份验证信息。
[npmAuth."<REGISTRY URL>"]
<TOKEN-PROPERTY> = "<TOKEN-VALUE>"
email = "<EMAIL>"
alwaysAuth = <BOOLEAN>

下表中的信息解释了如何指定配置文件的值:

Entry Description
[npmAuth."<REGISTRY-URL>"] 需要。注册表的URL。例如,[npmAuth."https://example.com:8081/mylocation"]
<TOKEN-PROPERTY> = "<TOKEN-VALUE>" 需要。从npm注册表生成的身份验证令牌。这可以是GUID、令牌,或者是专有格式的字符串。例如,可以是token = "<AUTH TOKEN>"(Bearer)或_auth = "<BASE64 TOKEN>"(Basic)。
email 可选。与注册表上用户邮箱地址匹配的用户邮箱地址。
alwaysAuth 可选。如果包元数据和压缩包不在同一服务器上,设置为true。通常,你可以从你生成的.npmrc文件中复制这个值。

Example using bearer authentication(使用Bearer身份验证的例子) 🔗

[npmAuth."http://localhost:8081/myrepository/mylocation"]
token = "NpmToken.2348c7ea-6f86-3dbe-86b6-f257e86569a8"
alwaysAuth = true

[npmAuth."http://localhost:4873"]
token = "eaJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZWFsX2dyb3VwcyI6WyJwYXNjYWxsIl0sIm5hbWUiOiJwYXNjYWxsIiwiZ3JvdXBzIjpbIn"

[npmAuth."https://api.bintray.example/npm/mycompany/myregistry"]
token = "aGFzY2FsbDo4ZWIwNTM5NzBjNTI3OTIwYjQ4MDVkYzY2YWEzNmQxOTkyNDYzZjky"
email = "username@example.com"
alwaysAuth = true

Configure basic authentication information(配置基本身份验证信息) 🔗

这些步骤以Azure DevOps为例,但是对于任何使用个人访问令牌(PAT)的平台,流程都是类似的。

开始前,如果还未安装Node.js,请进行安装。

  1. 获取你的Azure DevOps个人访问令牌(PAT),准备在后续步骤中使用。如果你需要重新生成PAT,请登录Azure DevOps https://dev.azure.com 并前往 用户设置 > 个人访问令牌。关于如何使用PAT的信息,可以参考Microsoft的文章,使用个人访问令牌。

  2. 从命令行,运行以下命令:

    node -e "require('readline').createInterface({input:process.stdin,output:process.stdout,historySize:0}).question('Enter PAT> ',p => {b64=Buffer.from(p.trim()).toString('base64');console.log(b64);process.exit();})"
    
  3. Enter PAT提示时,输入email:PAT,将其替换为:

    • email替换为与你的Azure DevOps帐户关联的电子邮件和.upmconfig.toml文件中指定的电子邮件
    • PAT替换为你在早期步骤中获得的PAT
  4. 命令将返回一个Base64加密的字符串。复制该字符串并将其赋值为.upmconfig.toml文件中的_auth键的值。

Example using basic authentication 🔗

[npmAuth."http://localhost:8081/myrepository/mylocation"]
_auth = "c19kaW5pcm9AaG90bWFpbC4jb206d3FzdzVhemU9Q=="
email = "username@example.com"
alwaysAuth = true

Customize the global cache(自定义全局缓存) 🔗

包管理器维护一个用于注册表数据和未压缩包的全局缓存。

全局缓存与包管理器为 资源商店 包维护的缓存是分开的。关于资源商店缓存的信息,请参考自定义资源商店缓存位置。

默认情况下,包管理器的全局缓存根目录有以下子目录,每个子缓存有不同的用途:

  • db子目录存储注册表数据(包元数据和tarballs)。
  • packages子目录存储未压缩的包tarballs的内容。
  • 如果你已启用Git LFS,git-lfs子目录会存储下载的Git大文件存储(LFS)文件。

包管理器将全局缓存存储在默认位置,你可以覆盖它。关于全局缓存根目录的默认位置的信息,请参考全局缓存。

你可能出于以下几个原因想要覆盖全局缓存位置:

  • 你想在你的内部驱动器上节省空间。
  • 你想在共享驱动器上存储缓存,以便其他人可以访问它。
  • 你想在非系统目录的文件夹中存储缓存。

从2023.2.0f1开始,db子目录的最大大小默认为10千兆字节(GB),你可以覆盖它。你可能出于以下几个原因想要覆盖db子目录的最大大小:

  • 如果你的可用磁盘空间很小,你可以降低限制以节省空间。
  • 如果你有大量可用的磁盘空间,你可以增加限制。这允许包管理器在缓存中存储更多数据,这样它可以从缓存中获取包,而不是再次下载它们。缓存的包安装更快,减少了网络使用。

以下表格列出了你可以用来覆盖默认属性的不同方法:

Method Global cache location db subdirectory max size Additional notes(额外说明)
Preferences window(偏好设置窗口) Yes No 这种方法因其易用性和持久性被推荐。当你使用这种方法更改包缓存位置时,Unity会为当前和未来的Unity编辑器会话存储偏好设置。
User configuration file(用户配置文件) Yes Yes 用户配置文件中的包缓存属性覆盖会持续到当前Unity编辑器会话之后。
Environment variables(环境变量) Yes Yes 默认情况下,此方法为当前的命令提示符(或终端)会话设置配置,但你可以在你的操作系统设置中使其永久化。高级用户可能在特定用例下更喜欢基于会话的变量。

注意:使用偏好设置窗口设置全局缓存位置也会在用户配置文件中设置cacheRoot属性。如果你想手动设置用户配置文件,请参考使用用户配置文件。

Important notes before you begin(开始前的重要声明) 🔗

  • 无论你选择哪种方法,更改缓存位置都会告诉包管理器从此时开始使用该位置。包管理器在原始位置存储的现有包会保留在那个文件夹结构中。
  • 如果你设置了db子目录的最大大小,且新大小小于该子目录的当前大小,包管理器会从缓存中逐出内容,直到达到新的限制。包管理器会按照最近最少使用的内容进行驱逐(基于安装到项目中的日期)。
  • 当你使用用户配置文件时,你的更改应用于当前的用户帐户。尽管存在全局配置文件,但你不能在全局配置文件中设置缓存覆盖。
  • 有一些因素会影响如何设置多个值与使用不同方法一起工作:
    • 如果你使用了环境变量方法来更改缓存位置,那么你不能使用偏好设置窗口来更改位置。
    • 设置环境变量优先于在用户配置文件或偏好设置窗口中应用相同的设置。
    • 如果你为注册表数据缓存(UPM_NPM_CACHE_PATH)、未压缩的包缓存(UPM_CACHE_PATH)或Git LFS缓存(UPM_GIT_LFS_CACHE_PATH)设置了环境变量,包管理器将使用环境变量设置的位置,而不管全局缓存根位置在哪里。
    • 如果你启用了Git LFS缓存(UPM_ENABLE_GIT_LFS_CACHE)但没有明确设置其路径(UPM_GIT_LFS_CACHE_PATH),包管理器会使用全局缓存根下的git-lfs目录作为其位置。

Using the Preferences window(偏好设置窗口) 🔗

若要使用偏好设置窗口来覆盖全局缓存的默认位置,请按照以下步骤操作。

  1. 使用以下方法之一打开偏好设置窗口:
    • 使用Unity编辑器的菜单,如偏好设置中所述。
    • 打开包管理器窗口,打开高级 img 菜单,并选择偏好设置
  2. 选择包管理器分类。
  3. 下,打开缓存位置旁边的菜单 img.
  4. 选择更改位置
  5. 为全局缓存选择一个新位置。

The Preferences window with the Package Manager category selected

选择了包管理器类别的偏好设定窗口

Using the user configuration file(使用用户配置文件) 🔗

你可以手动编辑用户配置文件,以覆盖全局缓存根的位置,或db子目录的最大大小,或两者都覆盖。

按照以下步骤编辑用户配置文件:

  1. 定位.upmconfig.toml用户配置文件。要找到文件位置,请参阅配置文件。如果文件不存在,则创建一个空文本文件。
  2. 要覆盖全局缓存根的位置,添加cacheRoot键,并将其值设置为自定义位置的绝对路径。重要提示:在TOML文件中设置Windows路径时,使用正斜杠(/)或双反斜杠(\\)。不要使用单个反斜杠(\),因为它们是标记转义序列的特殊字符,可能导致TOML解析错误。
  3. 要覆盖db子目录的最大大小,添加maxCacheSize键,并将其值设置为表示字节数的正整数。例如,要将大小设置为5GB,请赋值5000000000

在设置任一属性后,你无需重新启动Unity编辑器或Hub,更改即可生效。

Windows example

cacheRoot = "E:\\Unity\\cache"
maxCacheSize = 5000000000

macOS and Linux example

cacheRoot = "/dev/external/shared/Unity/cache"
maxCacheSize = 5000000000

Using environment variables(使用环境变量) 🔗

在涉及自动化或持续集成的场景中,在用户配置文件或偏好设置窗口中配置设置可能不太实际,而且更容易出错。在这种情况下,你可能会考虑使用环境变量来配置全局缓存及其附属缓存的设置。下列环境变量可供使用:

Environment variable Description
UPM_CACHE_ROOT 指定全局缓存的位置(包含注册表数据和未压缩包缓存的根文件夹)。
UPM_NPM_CACHE_PATH 指定您希望包管理器用作其注册表数据缓存的位置的绝对路径。默认情况下,这是全局缓存根目录下的db子目录。
UPM_CACHE_PATH 指定您希望包管理器存储包 tarball 的未压缩内容的位置的绝对路径。默认情况下,这是全局缓存根目录下的packages子目录。
UPM_ENABLE_GIT_LFS_CACHE 指定任何非空("")的值以启用 Git LFS 缓存。默认情况下,包管理器使用全局缓存根目录下的git-lfs子目录,除非您使用UPM_GIT_LFS_CACHE_PATH环境变量指定了不同的路径。
UPM_GIT_LFS_CACHE_PATH 指定您希望包管理器存储 Git LFS 缓存的位置的绝对路径。通过设置此路径,您自动启用 Git LFS 缓存。
UPM_MAX_CACHE_SIZE 以字节为单位,以正整数指定注册表数据缓存(db子目录)的最大大小。例如,要将大小设置为5GB,分配一个值为5000000000

重要提示:当你使用此方法时,请遵循以下指导原则:

  • 在设置环境变量之前,如果Unity编辑器和Unity Hub已经在运行,请关闭它们。
  • 在设置环境变量的同一个命令提示符或终端会话中启动Unity编辑器或Unity Hub。
  • 如果你在前述表格中设置了任何环境变量,每次启动Unity时都必须设置它们。

有关设置环境变量的信息,请参阅你的操作系统的文档。要了解环境变量的介绍,请参考 https://en.wikipedia.org/wiki/Environment_variable.

Customize the Asset Store cache location(自定义资源商店缓存位置) 🔗

包管理器为你从资源商店获取的包维护一个缓存。包管理器将此缓存存储在一个默认位置,你可以覆盖这个位置。

你可能有多种原因想要覆盖资源商店缓存的位置:

  • 你想节省内部驱动器的空间。
  • 你想将缓存存储在一个共享驱动器上,其他人可以访问。
  • 你想将缓存存储在不在系统目录中的文件夹。

默认情况下,包管理器对其资源商店包缓存使用以下文件夹结构:

<asset-store-cache-root>
  └── Asset Store-5.x
      └── <subfolders for Asset Store vendors>

关于资源商店包缓存根的默认位置的信息,请参考已下载资产文件的位置。

注意:包管理器为注册表包和资源商店包维护独立的缓存。关于覆盖全局缓存的默认位置的信息,请参考自定义全局缓存。

要覆盖包管理器对资源商店包的缓存的默认位置,你可以使用以下方法:

  • 推荐使用首选项窗口方法,因为它既简单又持久。当你使用该方法更改包缓存位置时,Unity会为当前会话和未来的会话存储偏好设置。
  • ASSETSTORE_CACHE_PATH环境变量方法不是永久性的,但高级用户在特定的使用情况下可能会发现它更可取。

Important notes before you begin(开始前的重要提示) 🔗

  • 无论你选择哪种方法,改变缓存位置都会告诉包管理器往后使用那个位置。包管理器在原始位置存储的现有包仍会保留在那个文件夹结构中。
  • 如果你使用环境变量方法更改了缓存位置,那么你就不能使用首选项窗口来更改位置。

Using the Preferences window(使用首选项窗口) 🔗

要使用首选项窗口覆盖资源商店包缓存的默认位置,请按照以下步骤操作。

  1. 使用以下方法之一打开首选项窗口:
    • 使用Unity编辑器的菜单,如首选项中所述。
    • 打开包管理器窗口,点击设置图标 img,然后选择 首选项
  2. 选择 包管理器 类别。
  3. 我的资源 下,打开 缓存位置 旁边的菜单 img.
  4. 选择 更改位置
  5. 为资源商店包缓存选择一个新的位置。

The Preferences window with the Package Manager category selected

选择首选项窗口的包管理器类别

Using the environment variable(使用环境变量) 🔗

在涉及自动化或持续集成的场景中,通过配置文件或首选项窗口配置设置的方式显得不够实用,而且更容易出错。在这样的场景下,你可能会考虑设置ASSETSTORE_CACHE_PATH环境变量,以覆盖资源商店包缓存的默认位置。

注意:在使用此方法时,请遵循以下指南:

  • 在设置环境变量之前,如果Unity编辑器和Unity Hub已经在运行,则关闭它们。
  • 从设置环境变量的同一命令提示符或终端会话中启动Unity编辑器或Unity Hub。
  • 每次启动Unity时,你都必须设置ASSETSTORE_CACHE_PATH环境变量。

关于设置环境变量的信息,请参照你的操作系统的文档。关于环境变量的入门介绍,请参考https://en.wikipedia.org/wiki/Environment_variable

Using private repositories with HTTPS Git URLs(使用HTTPS Git URL访问私有仓库) 🔗

当你在终端中使用Git通过HTTPS访问私有仓库时,Git会提示你输入用户名和密码。然后,Git将这些凭证提交给服务器,如果服务器接受这些凭证并允许访问仓库,Git就会继续执行命令。

当Unity包管理器使用Git URL获取包时,没有终端供用户输入凭证。因此,当服务器向Git请求凭证时,Git不会发出提示,而是向Unity包管理器报告错误。为了解决这个问题,你必须为Git配置一个Git凭证助手,而且该助手必须已经为该仓库加载了所需的凭证。如果凭证有效,Git可以成功执行Unity包管理器发出的命令。

注意:使用SSH协议的Git URL,包括SCP样式的语法时,Git凭证助手无效。

Git Credential ManagerGit(凭证管理器) 🔗

尽管Git支持多个凭证助手来存储凭证,但Git凭证管理器(GCM)仍是推荐的凭证助手。GCM灵活,易于安装,并得到了积极的支持。它基于.NET构建,这意味着它可以在支持.NET的Windows、macOS和Linux发行版上运行。

默认情况下,GCM使用Windows凭证管理器(在Windows上)和macOS钥匙串(在macOS上)作为配置的凭证存储。GCM没有为Linux配置默认的存储库。关于GCM支持的不同凭证存储配置的更多信息,请参考GCM凭证存储文档。

Prerequisites(先决条件) 🔗

在你可以使用HTTPS URL从私有Git仓库获取包之前,确保你已经安装了GCM。

Git for Windows安装程序包含一个步骤,可以自动安装和配置GCM。如果你在以下情况下,你也可以单独安装GCM:

  • 在Windows上用其他方法安装Git。
  • 使用macOS或Linux

关于安装GCM的更多信息,请参考GCM安装指南。

Procedure(操作步骤) 🔗

遵循以下步骤来访问使用HTTPS Git URL的私有仓库中的包:

  1. 在终端中运行以下命令,配置Git使用GCM:

    git config --global credential.helper manager
    
  2. 通过终端一次性访问仓库。例如,运行以下命令:

    git ls-remote --heads https://<url-to-repository> HEAD
    
  3. 当Git提示你时,输入你的凭证。如果你的用户账户可以访问远程Git服务器,且服务器接受你的凭证,那么Git凭证助手将会安全地存储你的凭证。

  4. 使用Unity包管理器。当需要时,它将使用你存储的凭证,从你有权限访问的基于HTTPS的仓库获取包。

Using passphrase-protected SSH keys with SSH Git URLs(使用口令保护的SSH密钥与SSH Git URL配合使用) 🔗

当你使用Git通过SSH访问私有仓库时,Git用SSH客户端和服务器建立了一个安全连接。在建立连接时,Git在SSH握手阶段使用了你配置的SSH密钥。在此阶段,SSH客户端需要能够读取你的密钥。然而,如果你用口令对你的密钥进行了加密,SSH客户端就无法直接使用这个密钥。在这种情况下,终端会提示你输入口令。在你输入正确的口令后,SSH连接就完成了,Git命令会使用这个连接进行运行。

当Unity包管理器使用Git URL获取包时,没有界面供你输入SSH客户端请求的凭证。因此,如果你用口令保护了你的SSH密钥文件,SSH客户端就无法建立连接,Git就会报告错误。为了解决这个问题,必须有一个SSH认证代理正在运行,并已加载SSH密钥,这样SSH客户端就可以在不需要口令的情况下使用它。

具体方法根据你的操作系统和你使用的SSH客户端而异:

  • 如果你使用Windows 10或更高版本及其内置的OpenSSH客户端,请参考在Windows(OpenSSH)上自动加载SSH密钥。
  • 如果你使用Windows和PuTTY及其认证代理(Pageant),请参考在Windows(PuTTY)上自动加载SSH密钥。
  • 如果你使用macOS,请参考在macOS上自动加载SSH密钥。

Loading SSH keys automatically on Windows (OpenSSH)在Windows上自动加载SSH密钥(OpenSSH) 🔗

如果你使用Windows及其内置的OpenSSH客户端,按照以下的步骤配置OpenSSH客户端,这样你就可以在不提示口令的情况下使用你的SSH密钥。

Prerequisites(前提条件) 🔗

  • Windows 10或更晚的版本。

Before you begin(在你开始之前) 🔗

检查是否有任何已存在的SSH密钥。请参考GitHub Docs文章,检查现有的SSH密钥。

如果你还没有SSH密钥:

  1. 按照GitHub Docs文章,生成新的SSH密钥来创建一个。
  2. 按照GitHub Docs文章,将新的SSH密钥添加到你的GitHub账户,添加新的SSH密钥到你的GitHub账户。

Procedure(步骤) 🔗

  1. 检查C:\Users\<YourUserName>\.ssh\config是否存在。注意:在一些应用程序中,如Git Bash,.ssh是一个隐藏的子目录。

  2. 如果C:\Users\<YourUserName>\.ssh\config不存在,则创建它。

  3. C:\Users\<YourUserName>\.ssh\config中添加以下内容,来在认证代理中设置要加载的密钥,并指定目标服务器的使用。确保你在标记为Host *的任何全局设置之前添加这个条目。

    Host SERVER_NAME
        IdentitiesOnly yes
        IdentityFile FILE_PATH
    
    • SERVER_NAME是使用IdentityFile指定文件的服务器。一个示例值是github.com
    • FILE_PATH是你创建的SSH文件的完全限定路径。一个示例值是C:\Users\<YourUserName>\.ssh\<FILE>,其中<FILE>可能是id_rsaid_ecdsaid_ed25519,或一个自定义名称。

    示例:

    Host github.com
        IdentitiesOnly yes
        IdentityFile C:/Users/user1/.ssh/id_ed25519
    
  4. 打开Windows PowerShell,确保你选择以管理员身份运行来打开它。

  5. 通过运行以下命令,配置SSH认证代理服务,以便它每次你重启电脑时启动:

    Get-Service ssh-agent | Set-Service -StartupType Automatic
    
  6. 运行以下命令以启动服务:

    Start-Service ssh-agent
    
  7. 运行以下命令以检查服务是否运行,并确认Status的值为Running

    Get-Service ssh-agent
    
  8. 将你的密钥文件加载到ssh-agent中,将<FILE>替换为你的密钥实际的文件名,然后在提示时输入你的密码。

    ssh-add $env:USERPROFILE\.ssh\<FILE>
    

    示例:

    ssh-add $env:USERPROFILE\.ssh\id_ed25519
    
  9. 确保Git使用Windows OpenSSH客户端,而不是Git附带的SSH客户端,可以使用以下任一方法:

    • 对于系统范围的配置,创建一个名为GIT_SSH_COMMAND的环境变量,其值为C:/Windows/System32/OpenSSH/ssh.exe重要提示:确保你在路径中使用正斜杠。

    • 要设置特定范围的配置,可以在终端中运行以下git config命令。可以参考git config文档了解详细信息。例如:

      git config --global core.sshCommand C:/Windows/System32/OpenSSH/ssh.exe
      
      • 重要: 确保你在路径中使用正斜杠。

现在,你可以使用Unity包管理器通过使用带有密码保护的SSH密钥从该Git仓库中获取包了。

Loading SSH keys automatically on Windows (PuTTY)在Windows上自动加载SSH密钥(PuTTY) 🔗

如果你使用PuTTY及其身份验证代理(Pageant)而非Windows内置的OpenSSH客户端,请按照以下步骤操作。例如,如果你使用SourceTree作为你的Git客户端,它会自带PuTTY(和Pageant)供你使用。

Before you begin(开始之前) 🔗

确保你已安装了包含Pageant的PuTTY套件。如果没有安装,可以在https://www.putty.org/ 下载。

检查你是否有任何现有的SSH密钥。参考GitHub文档文章,检查现有的SSH密钥。

如果你没有SSH密钥:

  1. 使用PuTTYgen应用生成一个私钥/公钥对,将其保存为私钥。参考PuTTY用户手册中的使用PuTTYgen,PuTTY密钥生成器。
  2. 按照GitHub文档文章,将新的SSH密钥添加到你的GitHub账户。

Procedure(操作步骤) 🔗

按照以下步骤在Windows上自动加载密钥和口令:

  1. 从PuTTY文件夹启动Pageant:开始菜单 > 所有程序 > PuTTY > Pageant
  2. 在系统托盘中找到Pageant图标. img
  3. 在系统托盘中右键点击Pageant图标并选择查看密钥Pageant密钥列表窗口会打开。
  4. 点击添加密钥
  5. 使用文件资源管理器窗口来选择你要加载的SSH密钥文件。确保选择的文件是.ppk扩展名,然后点击打开
  6. 如果该密钥受到口令保护,输入你的口令。
  7. 确保你选择的密钥现在已经在Pageant密钥列表窗口中列出。现在可在任何你的PuTTY会话中连接到任何服务器。

你可能已将Git配置为使用PuTTY的plink.exe程序。检查当使用SSH密钥时Git是否使用Pageant:

  1. 检查是否存在GIT_SSH_COMMAND环境变量。如果没有,创建它。
  2. 将其值设置为PuTTY的plink.exe文件的完全限定路径。默认位置为"C:\Program Files\PuTTY\plink.exe"重要: 如果路径包含空格,确保你使用引号将值括起来。

要在启动时自动加载私钥:

  1. 打开开始菜单并右键点击Pageant

  2. 选择更多 > 打开文件位置文件资源管理器窗口会打开。

  3. 右键点击Pageant并选择属性Pageant属性窗口会打开。

  4. 更新目标字段,通过添加你想在启动时加载的私钥的完全路径。每个密钥之间用空格分隔。例子:

      "C:\Program Files\PuTTY\pageant.exe" "C:\Users\user1\myKeys\privatekey.ppk"
    
  5. 选择应用然后选择确定

  6. 通过打开命令行并在你的仓库中运行git命令来测试你的配置,以确保无需输入口令就可以完成操作。

当Pageant运行且你输入了口令后,你可以使用Unity包管理器通过使用口令保护的SSH密钥从那个Git仓库中获取包。

下次当Pageant启动时,如果它受到口令保护,它会提示你输入口令。

要在Windows启动时自动加载Pageant,参考微软支持文章,将应用添加到Windows 10启动时自动运行。

Loading SSH keys automatically on macOS(在macOS上自动加载SSH密钥) 🔗

如果你使用macOS,按照以下步骤配置OpenSSH客户端,这样你就可以在不出现提示的情况下使用受口令保护的SSH密钥。

Prerequisites(前提条件) 🔗

  • macOS 10.13或更高版本。

Before you begin(开始之前) 🔗

检查是否有任何现有的SSH密钥。参考GitHub文档文章,检查现有的SSH密钥。

如果你没有SSH密钥:

  1. 按照GitHub文档文章,生成一个新的SSH密钥来创建一个。
  2. 按照GitHub文档文章,将新的SSH密钥添加到你的GitHub账户中。

Procedure(操作步骤) 🔗

  1. 检查你的家目录.ssh子目录是否包含一个config文件。注意.ssh是一个隐藏子目录。

  2. 如果~/.ssh/config文件不存在,创建它。

  3. 将以下内容添加到~/.ssh/config,以指定在认证代理中加载的密钥,并指明目标服务器的使用。确保你在标记为Host *的全局设置之前添加此条目。

    Host SERVER_NAME
        UseKeychain yes
        IdentitiesOnly yes
        IdentityFile FILE_PATH        
    
    • SERVER_NAME是使用IdentityFile指定文件的服务器。一个示例值是github.com
    • FILE_PATH是你创建的SSH文件的路径。一个示例值是~/.ssh/<FILE>,其中<FILE>可能是id_rsaid_ecdsaid_ed25519或自定义名称。

    示例:

    Host github.com
        UseKeychain yes
        IdentitiesOnly yes
        IdentityFile ~/.ssh/id_ed25519
    
  4. 打开终端应用程序。

  5. 将你的密钥文件加载到ssh-agent中,将<FILE>替换为你的密钥的实际文件名,然后在提示时输入你的口令。

    ssh-add ~/.ssh/<FILE>
    

    示例:

    ssh-add ~/.ssh/id_ed25519
    

配置完成。macOS默认启动ssh-agent,所以你现在可以使用Unity包管理器通过你的受口令保护的SSH密钥从那个Git仓库获取包。

结论 🔗

搬砖愉快!

Categories