`nuget.config` 參考

發行項
03/08/2024

NuGet 行為是由不同NuGet.Config或nuget.config檔案中的設定所控制，如一般 NuGet 組態中所述。

nuget.config 是包含最上層 <configuration> 節點的 XML 檔案，該節點則包含本主題中所述的區段項目。每個區段都包含零個或多個專案。請參閱設定檔範例。設定名稱會區分大小寫，而且值可以使用環境變數。

提示

nuget.config在專案存放庫的根目錄中新增檔案。這被視為最佳做法，因為它會提升可重複性，並確保不同的使用者具有相同的 NuGet 設定。您可能需要設定 clear 元素，以確保不會套用任何使用者或電腦特定的設定。深入瞭解如何套用設定。

config 區段

包含其他組態設定，可以使用 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	連線到套件來源時使用的 Proxy 設定；`http_proxy` 應該為 `http://<username>:<password>@<domain>` 格式。密碼會加密，且無法手動新增。對於 `no_proxy`，值是會略過 Proxy 伺服器的網域清單，並以逗號分隔。您可以為那些值選擇使用 http_proxy 及 no_proxy 環境變數。如需詳細資料，請參閱 NuGet proxy settings (NuGet proxy 設定) (skolima.blogspot.com)。
maxHttpRequestsPerSource	控制從 NuGet 傳送至每個套件來源的平行要求數目上限，以進行套件相依性解析和下載。上的 `dotnet.exe` 預設值衍生 `Int32.MaxValue` 自 `HttpClientHandler.MaxConnectionsPerServer` 屬性。此設定不會影響 `dotnet.exe` ， `Mac OS` 因為節流限制設定為 `16` ，以避免太多開啟的檔案錯誤。在上執行的預設值`NuGet client tools.NET Framework`，例如 `Visual Studio` ，且 `nuget.exe` 在 `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 區段

控制建置期間的套件還原。

機碼	值
已啟用	布林值，指出 NuGet 是否可以執行自動還原。您也可以使用 `True` 值來設定 `EnableNuGetPackageRestore` 環境變數，而不是在設定檔中設定此金鑰。
automatic	布林值，指出 NuGet 是否應該在建置期間檢查遺漏的套件。

範例：

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

solution 區段

控制解決方案的 packages 資料夾是否會包含在原始檔控制。本區段只適用於解決方案資料夾中的 nuget.config 檔。

機碼	值
disableSourceControlIntegration	布林值，指出當使用原始檔控制時是否要忽略 packages 資料夾。預設值為 false。

範例：

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

套件來源區段

packageSources、packageSourceCredentials、apikeys、activePackageSource、 disabledPackageSourcestrustedSigners 和 packageSourceMapping 全都會一起運作，以設定 NuGet 在安裝、還原和更新作業期間，如何與套件存放庫搭配運作。

命令nuget sources通常用來管理這些設定，但除了apikeys使用命令進行管理nuget setapikey，以及trustedSigners使用 nuget trusted-signers 命令管理的設定。

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

packageSources

列出所有已知的套件來源。還原作業期間以及使用 PackageReference 格式的任何專案會忽略順序。 NuGet 會遵循使用來安裝及更新專案 packages.config之來源的順序。

XML 屬性	目的
索引鍵	(要指派給套件來源的名稱)
值	套件來源的路徑或 URL。
protocolVersion	要使用的 NuGet 伺服器通訊協定版本。目前的版本是 “3”。當未指向結尾 `.json` 為的套件來源 URL 時，預設為「2」版（例如 https://api.nuget.org/v3/index.json）。 NuGet 3.0+ 支援。如需第 3 版通訊協定的詳細資訊，請參閱 NuGet 伺服器 API 。
allowInsecure 連線 ions	若為 false 或未指定，NuGet 會在來源使用 HTTP 而不是 https 時發出警告。如果您確信與這個來源的通訊永遠不會面臨攔截攻擊的風險，您可以將值設定為 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）來覆寫 <packageSources> NuGet.config 中定義的。

提示

指定節點具有 <clear /> 時，NuGet 會忽略先前針對該節點所定義的組態值。深入瞭解如何套用設定。

packageSourceCredentials

儲存來源的使用者名稱和密碼，通常使用 nuget sources 的 -username 和 -password 參數來指定。依預設會加密密碼，除非同時使用了 -storepasswordincleartext 選項。您可以選擇性地使用 -validauthenticationtypes 參數來指定有效的驗證類型。

機碼	值
username	純文字的來源使用者名稱。注意：環境變數可用來改善安全性。
password	加密的來源密碼。只有在 Windows 上才支援加密密碼，而且只能在相同電腦上使用時，以及透過與原始加密相同的使用者解密。
cleartextpassword	未加密的來源密碼。注意：環境變數可用來改善安全性。
validauthenticationtypes	此來源的有效驗證類型逗號分隔清單。如果伺服器公告 NTLM 或 Negotiate，而且必須使用基本機制傳送認證，例如，搭配內部部署 Azure DevOps Server 使用 PAT 時，請將設定為 `basic`。其他有效值包括 `negotiate`、`kerberos`、`ntlm` 和 `digest`，但這些值不太可能很有用。

警告

強烈建議不要將密碼儲存在純文本中。請注意，只有 Windows 支援加密的密碼。此外，只能在同一部計算機上使用時，以及原本加密它們的相同使用者解密。如需安全地管理認證的詳細資訊，請參閱從私人摘要取用套件的安全性最佳做法。

提示

如果傳遞password非加密的密碼，則會發生錯誤訊息「參數不正確」。

範例：

設定檔中，<packageSourceCredentials> 項目包含每個適用來源名稱的子節點 (名稱中的空格會取代為 _x0020_)。也就是說，對於名為 "Contoso" 和 "Test Source" 的來源，在使用加密的密碼時設定檔時包含下列內容：

<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。

受信任的存放庫也會指定serviceIndex存放庫的（這必須是有效的 https URI），而且可以選擇性地指定分號分隔清單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 套件作業判斷應該從何處下載套件標識碼的詳細數據。

本節目前只能手動管理。

區 packageSourceMapping 段只能包含 packageSource 區段。

packageSource

區段的 packageSourceMapping 子區段。包含對應，可協助 NuGet 判斷是否應該考慮來源以下載感興趣的套件。

機碼
區段中宣告 `packageSources` 的套件來源名稱。金鑰必須完全符合封裝來源的金鑰。

packageSource底下的packageSourceMapping區段是由唯一識別。key

套件

package是區段的packageSource一部分。

模式
套件來源對應語法所定義的模式。

範例：

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

packageManagement 區段

設定預設套件管理格式，即 packages.config 或 PackageReference。 SDK 樣式專案一律使用 PackageReference。

機碼	值
format	布爾值，表示預設套件管理格式。如果 `1`為，則格式為 PackageReference。如果 `0`為，則格式為 packages.config。
停用	布爾值，指出是否要在第一次安裝套件時顯示選取預設套件格式的提示。 `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` 環境變數支援

語法	Dir 分隔符	Windows nuget.exe	Windows dotnet.exe	Mac nuget.exe （在 Mono 中）	Mac dotnet.exe
`%MY_VAR%`	`/`	Yes	.是	.是	.是
`%MY_VAR%`	`\`	.是	.是	無	無
`$MY_VAR`	`/`	無	無	無	無
`$MY_VAR`	`\`	無	無	無	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` 參考

config 區段

bindingRedirects 區段

packageRestore 區段

solution 區段

套件來源區段

packageSources

packageSourceCredentials

apikeys

disabledPackageSources

activePackageSource

trustedSigners 區段

fallbackPackageFolders 區段

套件來源對應區段

packageSource

套件

packageManagement 區段

使用環境變數

`NuGet.Config` 環境變數支援

設定檔範例

意見反應

意見反應

其他資源

nuget.config 參考

config 區段

bindingRedirects 區段

packageRestore 區段

solution 區段

套件來源區段

packageSources

packageSourceCredentials

apikeys

disabledPackageSources

activePackageSource

trustedSigners 區段

fallbackPackageFolders 區段

套件來源對應區段

packageSource

套件

packageManagement 區段

使用環境變數

NuGet.Config 環境變數支援

設定檔範例

意見反應

意見反應

其他資源

`nuget.config` 參考

`NuGet.Config` 環境變數支援