`nuget.config` 参考

项目
11/09/2023

NuGet 行为由不同 NuGet.Config 或 nuget.config 文件中的设置来控制，如常见 NuGet 配置中所述。

nuget.config 是包含顶级 <configuration> 节点的 XML 文件，而该节点包含本主题中所述的节元素。每个部分均包含零个或多个项。请参阅示例配置文件。设置名称不区分大小写，并且值可以使用环境变量。

提示

在项目存储库的根目录中添加 nuget.config 文件。这被认为是一种最佳做法，因为它促进了可重复性，并可确保不同的用户具有相同的 NuGet 配置。可能需配置 clear 元素以确保不应用任何特定于用户或计算机的配置。详细了解如何应用设置。

配置节

包含杂项配置设置，可使用 nuget config 命令设置。

dependencyVersion 和 repositoryPath 仅适用于使用 packages.config 的项目。 globalPackagesFolder 仅适用于使用 PackageReference 格式的项目。

密钥	值
dependencyVersion（仅限于 `packages.config`）	包安装、还原和更新的默认 `DependencyVersion` 值（未直接指定 `-DependencyVersion` 开关时）。 NuGet 包管理器 UI 也使用此值。值为 `Lowest`、`HighestPatch`、`HighestMinor`、`Highest`。
globalPackagesFolder（仅限使用 PackageReference 的项目）	默认全局包文件夹的位置。默认值为 `%userprofile%\.nuget\packages` (Windows) 或 `~/.nuget/packages` (Mac/Linux)。相对路径可在项目特定的 `nuget.config` 文件中使用。此设置由优先的 `NUGET_PACKAGES` 环境变量覆盖。
repositoryPath（仅限于 `packages.config`）	安装 NuGet 包的位置，而非默认的 `$(Solutiondir)/packages` 文件夹。相对路径可在项目特定的 `nuget.config` 文件中使用。
defaultPushSource	如果操作未找到任何其他包源，则会标识应用作默认值的包源 URL 或路径。
http_proxy http_proxy.user http_proxy.password no_proxy	连接到包源时要使用的代理设置；`http_proxy` 应为 `http://<username>:<password>@<domain>` 格式。密码已加密，且不能手动添加。对于 `no_proxy`，该值是绕过代理服务器的域的列表（以逗号分隔）。可将 http_proxy 和 no_proxy 环境变量交替用于这些值。有关其他详细信息，请参阅 NuGet 代理设置 (skolima.blogspot.com)。
maxHttpRequestsPerSource	控制从 NuGet 发送到包依赖项解析和下载的每个包源的最大并行请求数。 `dotnet.exe` 的默认值为 `Int32.MaxValue`（从 `HttpClientHandler.MaxConnectionsPerServer` 属性派生）。此设置不影响 `Mac OS` 的 `dotnet.exe`，因为已将限制设为 `16` 从而避免出现过多打开文件错误。运行于 `.NET Framework`（例如 `Visual Studio` 和 `nuget.exe`）的 `NuGet client tools` 的默认值为 `64`（在 `Windows` 上）和 `1`（在 `Mono` 上）。 `Packages.config` 式项目的默认值被设为 `Environment.ProcessorCount`。将 `maxHttpRequestsPerSource` 属性配置为小于默认值的值可能会影响 NuGet 性能。
signatureValidationMode	指定用于验证包安装和还原的包签名的验证模式。值为 `accept`、`require`。默认为 `accept`。

示例：

<config>
    <add key="dependencyVersion" value="Highest" />
    <add key="globalPackagesFolder" value="c:\packages" />
    <add key="repositoryPath" value="c:\installed_packages" />
    <add key="http_proxy" value="http://company-squid:3128@contoso.com" />
    <add key="signatureValidationMode" value="require" />
    <add key="maxHttpRequestsPerSource" value="16" />
</config>

bindingRedirects 节

在安装包时，配置 NuGet 是否执行自动绑定重定向。

密钥	值
skip	指示是否跳过自动绑定重定向的布尔。默认值为 false。

示例：

<bindingRedirects>
    <add key="skip" value="True" />
</bindingRedirects>

packageRestore 节

在生成期间控制包还原。

密钥	值
enabled	指示 NuGet 是否可执行自动还原的布尔。还可以使用 `True` 的值设置 `EnableNuGetPackageRestore` 环境变量，而不是在配置文件中设置此密钥。
automatic	指示 NuGet 是否应在生成期间检查缺少的包。

示例：

<packageRestore>
    <add key="enabled" value="true" />
    <add key="automatic" value="true" />
</packageRestore>

解决方案节

控制解决方案的 packages 文件夹是否包括在源代码管理中。此节仅适用于解决方案文件夹中的 nuget.config 文件。

密钥	值
disableSourceControlIntegration	指示在使用源代码管理时是否忽略包文件夹的布尔。默认值为 false。

示例：

<solution>
    <add key="disableSourceControlIntegration" value="true" />
</solution>

包源节

packageSources、packageSourceCredentials、apikeys、activePackageSource、disabledPackageSources、trustedSigners 和 packageSourceMapping 会共同配置在安装、还原和更新操作期间 NuGet 使用包存储库的方式。

nuget sources 命令通常用于管理这些设置，但用 nuget setapikey 命令来管理的 apikeys 以及用 nuget trusted-signers 命令来管理的 trustedSigners 除外。

请注意，nuget.org 的源 URL 是 https://api.nuget.org/v3/index.json。

packageSources

列出所有已知包源。在还原操作期间以及针对采用 PackageReference 格式的所有项目，均会忽略该顺序。对于使用 packages.config 的项目，NuGet 遵循针对安装和更新操作的源的顺序。

XML 特性	目的
键	（要分配给包源的名称）
值	包源的路径或 URL。
protocolVersion	要使用的 NuGet 服务器协议版本。当前版本为“3”。当未指向以 `.json` 结尾的包源 URL（例如 https://api.nuget.org/v3/index.json）时，默认为版本“2”。在 NuGet 3.0 及以上版本中受到支持。有关版本 3 协议的详细信息，请参阅 NuGet 服务器 API。
allowInsecureConnections	如果为 false 或未指定，则当源使用 http 而不是 https 时，NuGet 会发出警告。如果你确信与此源的通信绝不会面临拦截攻击的风险，则可将该值设为 true 以不显示此警告。在 NuGet 6.8 及以上版本中受到支持。

示例：

<packageSources>
    <clear />    
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
    <add key="Contoso" value="https://contoso.com/packages/" />
    <add key="http-source" value="http://httpsourcetrusted/" allowInsecureConnections="true" />
    <add key="Test Source" value="c:\packages" />
</packageSources>

注意

使用 CLI 时，可使用 RestoreSources MSBuild 属性或 --source(.NET CLI) | -Source(NuGet CLI) 以覆盖 NuGet.config 中定义的 <packageSources>。

提示

当给定节点中存在 <clear /> 时，NuGet 将忽略之前为该节点定义的配置值。详细了解如何应用设置。

packageSourceCredentials

存储源的用户名和密码，通常通过 nuget sources 使用 -username 和 -password 开关指定。默认情况下密码会进行加密，除非还使用了 -storepasswordincleartext 选项。（可选）可使用 -validauthenticationtypes 开关指定有效的身份验证类型。

密钥	值
username	纯文本形式的源用户名。注意：环境变量可用于提升安全性。
password	源的加密密码。加密的密码仅在 Windows 上受到支持，且只能在同一计算机上使用时通过执行原始加密的同一用户来解密。
cleartextpassword	源的未加密密码。注意：环境变量可用于提升安全性。
validauthenticationtypes	此源的有效身份验证类型的逗号分隔列表。如果服务器公布 NTLM 或协商，并且你必须使用基本机制发送凭据（例如，在本地 Azure DevOps Server 中使用 PAT 时），则将此项设置为 `basic`。其他有效值包括 `negotiate`、`kerberos`、`ntlm` 和 `digest`，但这些值不太可能有用。

警告

强烈建议不要以明文形式存储密码。请注意，仅 Windows 支持加密密码。此外，加密密码只能在同一台计算机，由最初对其进行加密的同一用户解密。有关安全地管理凭据的详细信息，请参阅使用私有源的包的安全最佳做法。

提示

如果为 password 传递了非加密密码，则会出现错误消息“参数不正确”。

示例：

在配置文件中，<packageSourceCredentials> 元素包含每个适用源名称的子节点（名称中的空格被替换为 _x0020_）。也就是说，对于名为“Contoso”和“测试源”的源，使用加密密码时，配置文件包含以下内容：

<packageSourceCredentials>
    <Contoso>
        <add key="Username" value="user@contoso.com" />
        <add key="Password" value="..." />
    </Contoso>
    <Test_x0020_Source>
        <add key="Username" value="user" />
        <add key="Password" value="..." />
    </Test_x0020_Source>
</packageSourceCredentials>

此外，还可提供有效的身份验证方法。

<packageSourceCredentials>
    <Contoso>
        <add key="Username" value="user@contoso.com" />
        <add key="Password" value="..." />
        <add key="ValidAuthenticationTypes" value="basic" />
    </Contoso>
    <Test_x0020_Source>
        <add key="Username" value="user" />
        <add key="Password" value="..." />
        <add key="ValidAuthenticationTypes" value="basic, negotiate" />
    </Test_x0020_Source>
</packageSourceCredentials>

使用存储在环境变量中的未加密密码时：

<packageSourceCredentials>
    <Contoso>
        <add key="Username" value="user@contoso.com" />
        <add key="ClearTextPassword" value="%ContosoPassword%" />
    </Contoso>
    <Test_x0020_Source>
        <add key="Username" value="user" />
        <add key="ClearTextPassword" value="%TestSourcePassword%" />
    </Test_x0020_Source>
</packageSourceCredentials>

使用未加密密码时：

警告

强烈建议不要以明文形式存储密码。

<packageSourceCredentials>
    <Contoso>
        <add key="Username" value="user@contoso.com" />
        <add key="ClearTextPassword" value="33f!!lloppa" />
    </Contoso>
    <Test_x0020_Source>
        <add key="Username" value="user" />
        <add key="ClearTextPassword" value="hal+9ooo_da!sY" />
    </Test_x0020_Source>
</packageSourceCredentials>

apikeys

存储使用 API 密钥身份验证的源的密钥，如使用 nuget setapikey 命令设置。

密钥	值
（源 URL）	加密的 API 密钥。

示例：

<apikeys>
    <add key="https://MyRepo/ES/api/v2/package" value="encrypted_api_key" />
</apikeys>

disabledPackageSources

标识当前已禁用的源。可以为空。除非在此部分禁用特定源，否则它们将被启用。

密钥	值
（源名称）	指示源是否禁用的布尔。

示例：

<disabledPackageSources>
    <add key="Contoso" value="true" />
</disabledPackageSources>

<!-- Empty list -->
<disabledPackageSources />

在以上示例中，包源 Contoso 处于禁用状态，因而不会用于下载或安装包。

activePackageSource

（仅限于 2.x；3.x+ 中已弃用）

标识到当前活动的源或指示所有源的聚合。

密钥	值
（源名称）或 `All`	如果密钥是源的名称，则值为源路径或 URL。如果为 `All`，值应为 `(Aggregate source)`，从而组合其他未禁用的所有包源。

示例：

<activePackageSource>
    <!-- Only one active source-->
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />

    <!-- All non-disabled sources are active -->
    <add key="All" value="(Aggregate source)" />
</activePackageSource>

trustedSigners 部分

存储用于在安装或还原时允许使用包的可信签名者。当用户将 signatureValidationMode 设为 require 时，此列表不能为空。

可使用 nuget trusted-signers 命令更新此部分。

架构：

可信签名者拥有一组 certificate 项，它们可用于登记标识给定签名者的所有证书。可信签名者可为 Author 或 Repository。

可信存储库还会为存储库（必须为有效 https URI）指定 serviceIndex，且可选择性地指定以分号分隔的 owners 的列表，从而进一步限制在该特定存储库中受到信任的人员。

用于证书指纹的受支持哈希算法为 SHA256、SHA384 和 SHA512。

如果 certificate 将 allowUntrustedRoot 指定为 true，则在生成证书链以作为签名验证的其中一部分时，可将给定证书链接到不受信任的根。

示例：

<trustedSigners>
    <author name="microsoft">
        <certificate fingerprint="3F9001EA83C560D712C24CF213C3D312CB3BFF51EE89435D3430BD06B5D0EECE" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
        <certificate fingerprint="AA12DA22A49BCE7D5C1AE64CC1F3D892F150DA76140F210ABD2CBFFCA2C18A27" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
        <certificate fingerprint="566A31882BE208BE4422F7CFD66ED09F5D4524A5994F50CCC8B05EC0528C1353" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
    </author>
    <repository name="nuget.org" serviceIndex="https://api.nuget.org/v3/index.json">
        <certificate fingerprint="0E5F38F57DC1BCC806D8494F4F90FBCEDD988B46760709CBEEC6F4219AA6157D" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
        <certificate fingerprint="5A2901D6ADA3D18260B9C6DFE2133C95D74B9EEF6AE0E5DC334C8454D1477DF4" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
        <owners>microsoft;aspnet;nuget</owners>
    </repository>
</trustedSigners>

fallbackPackageFolders 部分

(3.5+) 提供一种预安装包方法，以便在回退文件夹中找到包时无需执行任何操作。回退包文件夹的文件夹和文件结构与全局包文件夹完全相同：存在 .nupkg，且会提取所有文件。

此配置的查找逻辑为：

查看全局包文件夹以确定是否已下载包/版本。
查看回退文件夹以确定是否存在包/版本匹配项。

如果任一查找成功，则无需进行下载。

如果未找到匹配项，NuGet 则会先检查文件源再检查 http 源，然后下载包。

密钥	值
（回退文件夹的名称）	回退文件夹的路径。

示例：

<fallbackPackageFolders>
   <add key="XYZ Offline Packages" value="C:\somePath\someFolder\"/>
</fallbackPackageFolders>

包源映射部分

packageSourceMapping 部分包含有助于 NuGet 包操作确定从何处下载包 ID 的详细信息。

此部分目前只能手动管理。

packageSourceMapping 部分只能包含 packageSource 部分。

packageSource

packageSourceMapping 部分的子部分。包含一个映射，从而帮助 NuGet 确定是否应考虑此源来下载感兴趣的包。

密钥
在 `packageSources` 部分声明的包源的名称。此密钥必须与包源的密钥完全匹配。

packageSourceMapping 下的 packageSource 部分由 key 进行唯一标识。

package

package 是 packageSource 部分的一部分。

模式
由包源映射的语法定义的模式。

示例：

<packageSourceMapping>
  <packageSource key="contoso.com">
    <package pattern="Contoso.*" />
  </packageSource>
</packageSourceMapping>

packageManagement 部分

设置默认包管理格式，即 packages.config 或 PackageReference。 SDK 式项目始终使用 PackageReference。

密钥	值
format	指示默认包管理格式的布尔值。如果为 `1`，则格式为 PackageReference。如果为 `0`，则格式为 packages.config。
disabled	一个布尔值，指示是否在首次安装包时显示用于选择默认包格式的提示。 `False` 会隐藏该提示。

示例：

<packageManagement>
   <add key="format" value="1" />
   <add key="disabled" value="False" />
</packageManagement>

提示

当给定节点中存在 <clear /> 时，NuGet 将忽略之前为该节点定义的配置值。详细了解如何应用设置。

使用环境变量

可以在 nuget.config 值中使用环境变量 (NuGet 3.4 +) 在运行时应用设置。

例如，如果 Windows 上的 HOME 环境变量设置为 c:\users\username，则配置文件中 %HOME%\NuGetRepository 的值解析为 c:\users\username\NuGetRepository。

请注意，即使在 Mac/Linux 上也必须使用 Windows 式环境变量（以 % 开头和结尾）。在配置文件中使用 $HOME/NuGetRepository 则不会进行解析。在 Mac/Linux 上，%HOME%/NuGetRepository 的值将解析为 /home/myStuff/NuGetRepository。

如果未找到环境变量，NuGet 会使用配置文件中的文本值。例如，%MY_UNDEFINED_VAR%/NuGetRepository 会解析为 path/to/current_working_dir/$MY_UNDEFINED_VAR/NuGetRepository

下表显示针对 NuGet.Config 文件的环境变量语法和路径分隔符支持。

`NuGet.Config` 环境变量支持

语法	目录分隔符	Windows nuget.exe	Windows dotnet.exe	Mac nuget.exe（在 Mono 中）	Mac dotnet.exe
`%MY_VAR%`	`/`	是	是	是	是
`%MY_VAR%`	`\`	是	是	否	No
`$MY_VAR`	`/`	No	No	No	No
`$MY_VAR`	`\`	No	No	No	否

示例配置文件

以下 nuget.config 示例文件对包括可选设置的部分设置进行了说明：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <config>
        <!--
            Used to specify the default location to expand packages.
            See: nuget.exe help install
            See: nuget.exe help update

            In this example, %PACKAGEHOME% is an environment variable.
            This syntax works on Windows/Mac/Linux
        -->
        <add key="repositoryPath" value="%PACKAGEHOME%/External" />

        <!--
            Used to specify default source for the push command.
            See: nuget.exe help push
        -->

        <add key="defaultPushSource" value="https://MyRepo/ES/api/v2/package" />

        <!-- Proxy settings -->
        <add key="http_proxy" value="host" />
        <add key="http_proxy.user" value="username" />
        <add key="http_proxy.password" value="encrypted_password" />
    </config>

    <packageRestore>
        <!-- Allow NuGet to download missing packages -->
        <add key="enabled" value="True" />

        <!-- Automatically check for missing packages during build in Visual Studio -->
        <add key="automatic" value="True" />
    </packageRestore>

    <!--
        Used to specify the default Sources for list, install and update.
        See: nuget.exe help list
        See: nuget.exe help install
        See: nuget.exe help update
    -->
    <packageSources>
        <clear />
        <add key="NuGet official package source" value="https://api.nuget.org/v3/index.json" />
        <add key="MyRepo - ES" value="https://MyRepo/ES/nuget" />
    </packageSources>

    <!-- Used to store credentials -->
    <packageSourceCredentials />

    <!-- Used to disable package sources  -->
    <disabledPackageSources />

    <!--
        Used to specify default API key associated with sources.
        See: nuget.exe help setApiKey
        See: nuget.exe help push
        See: nuget.exe help mirror
    -->
    <apikeys>
        <add key="https://MyRepo/ES/api/v2/package" value="encrypted_api_key" />
    </apikeys>

    <!--
        Used to specify trusted signers to allow during signature verification.
        See: nuget.exe help trusted-signers
    -->
    <trustedSigners>
        <author name="microsoft">
            <certificate fingerprint="3F9001EA83C560D712C24CF213C3D312CB3BFF51EE89435D3430BD06B5D0EECE" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
            <certificate fingerprint="AA12DA22A49BCE7D5C1AE64CC1F3D892F150DA76140F210ABD2CBFFCA2C18A27" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
            <certificate fingerprint="566A31882BE208BE4422F7CFD66ED09F5D4524A5994F50CCC8B05EC0528C1353" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
        </author>
        <repository name="nuget.org" serviceIndex="https://api.nuget.org/v3/index.json">
            <certificate fingerprint="0E5F38F57DC1BCC806D8494F4F90FBCEDD988B46760709CBEEC6F4219AA6157D" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
            <certificate fingerprint="5A2901D6ADA3D18260B9C6DFE2133C95D74B9EEF6AE0E5DC334C8454D1477DF4" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
            <owners>microsoft;aspnet;nuget</owners>
        </repository>
    </trustedSigners>
</configuration>

`nuget.config` 参考

配置节

bindingRedirects 节

packageRestore 节

解决方案节

包源节

packageSources

packageSourceCredentials

apikeys

disabledPackageSources

activePackageSource

trustedSigners 部分

fallbackPackageFolders 部分

包源映射部分

packageSource

package

packageManagement 部分

使用环境变量

`NuGet.Config` 环境变量支持

示例配置文件

反馈

反馈

其他资源

nuget.config 参考

配置节

bindingRedirects 节

packageRestore 节

解决方案节

包源节

packageSources

packageSourceCredentials

apikeys

disabledPackageSources

activePackageSource

trustedSigners 部分

fallbackPackageFolders 部分

包源映射部分

packageSource

package

packageManagement 部分

使用环境变量

NuGet.Config 环境变量支持

示例配置文件

反馈

反馈

其他资源

`nuget.config` 参考

`NuGet.Config` 环境变量支持