從已驗證的來源取用套件

2025-05-13

許多 NuGet 作業，例如還原和安裝，都需要與一或多個套件來源通訊，這些來源可以在 nuget.config 檔案中設定。

備註

使用您信任的套件來源。

針對 HTTP 提要，NuGet 會發出未經認證的請求，如果伺服器以 HTTP 401 回應，NuGet 會依下列順序搜尋認證：

環境變數 NuGetPackageSourceCredentials_{name}。
nuget.config 檔案中的認證。
如果您的套件來源提供 NuGet 認證提供者，請使用 NuGet 認證提供者。

您需要使用的認證取決於套件來源。因此，除非您使用認證提供者，否則您應該向套件來源檢查要使用的認證。套件來源通常會禁止您使用您用於登入網站的密碼來連接 NuGet。您通常需要建立個人存取令牌作為 NuGet 的密碼，但您應該檢查您所使用的 NuGet 伺服器的文件。某些套件來源，例如 Azure DevOps 和 GitHub，具有限定範圍的存取令牌，因此您可能需要確定您所建立的任何令牌都包含必要的範圍。

管理認證的安全性最佳做法

雖然 NuGet 會依上述順序搜尋認證，但建議您依照下列順序，在使用私人摘要進行驗證時安全地管理認證：

認證提供者：強烈建議盡可能使用認證提供者。此方法可避免將秘密儲存在純文本中，並將不小心透過原始檔控制公開秘密的風險降到最低。此外，它通常會減少認證到期或變更時需要更新的位置數目。如果認證提供者支援單一登錄，它可能會降低登入的頻率，或儲存認證的位置數目。如需詳細資訊，請參閱認證提供者一節。
nuget.config中的加密認證 ：如果認證提供者無法使用，您應該考慮使用加密的認證。此方法藉由以加密格式儲存認證來提供額外的安全性層。如需詳細資訊，請參閱 nuget.config 檔案中的認證一節。

備註

請注意，只有 Windows 支援加密的密碼。此外，它們只能在同一部電腦上由原本加密它們的使用者進行解密。
在 nuget.config中使用環境變數巨集 ：如果無法使用加密認證，請考慮使用環境變數巨集將認證儲存在 nuget.config 檔案中。此方法可讓您參考包含實際認證的環境變數。其可增強透明度，並協助使用者瞭解其認證設定方式。如需詳細資訊，請參閱 nuget.config 檔案中的認證一節。
直接使用環境變數：作為後援選項，您可以將認證直接儲存在環境變數中。不過，請注意，相較於在 nuget.config 檔案中使用環境變數巨集，此方法可提供較少的可見度和控制。如需詳細資訊，請參閱環境變數中認證一節。
NuGet.Config 中的純文本認證：強烈建議您使用上述其中一個選項。如果這些選項不可行，您可以將認證儲存在 nuget.config 檔案中。不過，只有在沒有其他安全選項可供使用的環境中，才應該使用此選項。如需詳細資訊，請參閱 nuget.config 檔案中的認證一節。

警告

將認證以純文本儲存在 nuget.config 檔案中，特別是在原始碼控制中檔案儲存時，可能會有風險，因為它會增加意外認證洩露的機會。如果您必須將認證儲存在 nuget.config 檔案中，請考慮使用上述其中一個更安全的選項。

藉由遵守這些最佳做法，您可以安全地驗證私人摘要，同時將敏感性資訊暴露的風險降到最低。

環境變數中的認證

NuGet 會搜尋名為 NuGetPackageSourceCredentials_{name}的環境變數，其中 {name} 是您nuget.config 檔案套件來源中的值key="name"。環境變數的值必須是 Username={username};Password={password}，而且可以選擇性地包含 ;ValidAuthenticationTypes={types}。如果環境變數不符合 NuGet 慣例，或值不符合 NuGet 的預期模式，NuGet 會以無訊息方式忽略環境變數，並繼續搜尋其他地方套件來源的認證。沒有記錄可發出 NuGet 使用環境變數認證的訊號，如果環境變數包含過期的秘密，而且新密碼會新增至 nuget.config 檔案，因為組態檔優先順序較低，因此在偵錯驗證問題時可能會造成困難。

小提示

在 CI/CD 管線中使用環境變數是將記錄中擷取秘密風險降到最低的絕佳選擇。

例如，請考慮下列 nuget.config 檔案：

<configuration>
  <packageSources>
    <clear />
    <add key="Contoso" value="https://nuget.contoso.com/v3/index.json" />
  </packageSources>
</configuration>

在這裡情況下，來源名稱為 Contoso ，而 NuGet 會尋找環境變數名稱 NuGetPackageSourceCredentials_Contoso。某些平臺會區分大小寫，因此請小心針對環境名稱和來源名稱使用正確的大寫和小寫字元，如 nuget.config 檔案中所定義。

如果使用者名稱稱為 nugetUser ，且密碼為 secret123，則環境變數的值應設定為 Username=nugetUser;Password=secret123。如果 NuGet 只應該將此認證用於 HTTP 基本身份驗證，但不能使用其他驗證配置，您可以將環境變數的值設定為 Username=nugetUser;Password=secret123;ValidAuthenticationTypes=Basic。如需有效驗證類型的詳細資訊，請參閱 nuget.config 檔案中的套件認證檔。

備註

環境變數對允許的字元有限制，而不同的作系統可能會有不同的限制。例如，不允許空格。因此，您可以使用此環境變數功能來為套件來源指定 NuGet 認證，尤其是那些在你的平台環境變數中使用不合法字元的套件來源。在這種情況下，您應該重新命名 nuget.config 檔案中的套件來源。

nuget.config 檔案中的認證

nuget.config 檔案可以包含套件來源認證。如需詳細資訊，請參閱套件來源認證的 nuget.config 檔案參考檔一節，包括語法。不過，在命令行上更容易使用 dotnet nuget update source 來設定認證。

警告

在 nuget.config 檔案中設定認證時，請小心，尤其是在將認證儲存為純文本時。如果認證寫入原始檔控制中的 nuget.config 檔案，則意外洩漏秘密的風險會增加。

當 NuGet 從多個檔案累積設定時，建議將認證儲存至使用者 nuget.config 檔案。我們也建議將套件來源儲存在方案（原始程式碼存放庫） nuget.config 檔案中，包括 <clear /> 專案，以取得建置可靠性。

nuget.config 檔案中的使用者名稱和純文本密碼可以藉由將新增%至您想要使用的環境變數名稱的開頭和結尾，來使用環境變數。如需詳細資訊，請參閱使用環境變數 的nuget.config 參考檔。

認證提供者

NuGet 具有擴充性模型，允許外掛程式提供 NuGet 認證。 NuGet 要探索的認證提供者必須安裝的路徑，在 .NET Framework（NuGet.exe、MSBuild 和 Visual Studio）與 .NET SDK（在 .NET 5+ 執行時間上運行）之間是不同的。

NuGet 的功能概念是在互動模式或非互動模式中運作。在非互動式模式中時，系統會要求認證提供者不要封鎖 NuGet。在互動式模式中，認證提供者可能會提示您登入。不同的工具有不同的預設值，因此視您的案例而定，互動模式可能需手動選擇啟用或停用。

工具	預設	切換
`dotnet` CLI（命令列介面）	非互動式	`--interactive` 論點。例如： `dotnet restore --interactive` 。
MSBuild	非互動式	`NuGetInteractive` MSBuild 屬性。例如： `msbuild -t:restore -p:NuGetInteractive=true` 。
NuGet.exe	互動式	`-NonInteractive` 參數。例如： `nuget.exe restore -NonInteractive` 。
Visual Studio	互動式	無法以非互動式模式執行。

NuGet.exe 同時支援 V1 和 V2 認證提供者，而 MSBuild 和 .NET SDK 僅支援跨平臺（V2）外掛程式。

在 Visual Studio 中，NuGet 具有 Visual Studio 認證提供者介面，認證提供者可用來提供圖形化登入體驗，或視需要呼叫 Visual Studio API。如果 Visual Studio 中的 NuGet 找不到處理來源的 Visual Studio 認證提供者，則會回復至命令行認證提供者。

Visual Studio 2017 15.9 版和更新版本包含 Azure Artifacts 的認證提供者，可在 Visual Studio、MSBuild 和 NuGet.exe內運作。不過，Visual Studio 不包含 .NET SDK 的認證提供者，因此必須個別安裝才能使用 dotnet CLI。

認證提供者清單

以下是我們所知道的認證提供者清單：