nuget.config 参考

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

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

提示

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

配置节

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

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

密钥
dependencyVersion(仅限于 packages.config 包安装、还原和更新的默认 DependencyVersion 值(未直接指定 -DependencyVersion 开关时)。 NuGet 包管理器 UI 也使用此值。 值为 LowestHighestPatchHighestMinorHighest
globalPackagesFolder 默认全局包文件夹的位置。 默认值为 %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 OSdotnet.exe,因为已将限制设为 16 从而避免出现过多打开文件错误。 运行于 .NET Framework(例如 Visual Studionuget.exe)的 NuGet client tools 的默认值为 64(在 Windows 上)和 1(在 Mono 上)。 Packages.config 式项目的默认值被设为 Environment.ProcessorCount。 将 maxHttpRequestsPerSource 属性配置为小于默认值的值可能会影响 NuGet 性能。
signatureValidationMode 指定用于验证包安装和还原的包签名的验证模式。 值为 acceptrequire。 默认为 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>

包源节

packageSourcespackageSourceCredentialsapikeysactivePackageSourcedisabledPackageSourcestrustedSignerspackageSourceMapping 会共同配置在安装、还原和更新操作期间 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 及以上版本中受到支持。
disableTLSCertificateValidation 此配置属性允许禁用 HTTPS 服务器的 SSL/TLS 证书验证。 如果设置为 true,服务器将忽略与 SSL/TLS 证书相关的任何错误(例如,过期证书或自签名证书),并在未进行验证的情况下建立连接。 在 NuGet 6.11 及以上版本中受到支持。

示例:

<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="Invalid-certificate-https-source" value="https://httpsSourceTrusted/" disableTLSCertificateValidation="true" />
    <add key="Test Source" value="c:\packages" />
</packageSources>

注意

使用信任的包源。

注意

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

提示

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

auditSources

列出所有已知的审核源,NuGet 审核将在还原期间使用。 如果未提供审核源,则还原将使用包源并抑制 NU1905auditSources 已添加至 NuGet 6.12

审核源支持与 packageSourcesprotocolVersionallowInsecureConnections)相同的属性,使用 packageSourceCredentials 配置需要身份验证的源,与 packageSources 的方法相同。

示例:

<auditSources>
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
</auditSources>

packageSourceCredentials

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

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

警告

强烈建议不要以明文形式存储密码。 请注意,仅 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 项,它们可用于登记标识给定签名者的所有证书。 可信签名者可为 AuthorRepository

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

用于证书指纹的受支持哈希算法为 SHA256SHA384SHA512

如果 certificateallowUntrustedRoot 指定为 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" />
        <certificate fingerprint="1F4B311D9ACC115C8DC8018B5A49E00FCE6DA8E2855F9F014CA6F34570BC482D" 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

packagepackageSource 部分的一部分。

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

示例:

<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" />
            <certificate fingerprint="1F4B311D9ACC115C8DC8018B5A49E00FCE6DA8E2855F9F014CA6F34570BC482D" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
            <owners>microsoft;aspnet;nuget</owners>
        </repository>
    </trustedSigners>
</configuration>