常用的 NuGet 組態

發行項
02/01/2024

NuGet 的行為是由一或多個 NuGet.Config （XML）檔案中累積的設定所驅動，這些檔案可以存在於解決方案中-（如果沒有使用方案，則為專案）、使用者和全計算機層級。全域 NuGetDefaults.Config 檔案還會特別設定套件來源。設定適用於 CLI、套件管理員主控台和套件管理員 UI 中發出的所有命令。

組態檔位置和使用

範圍	`NuGet.Config` 檔案位置	描述
解決方案	目前的資料夾 (也稱為解決方案資料夾) 或最高到磁碟機根目錄的任何資料夾。	在解決方案資料夾中，設定會套用到子資料夾中的所有專案。請注意，若設定檔放在專案資料夾中，它對於該專案沒有任何影響。在命令行上還原專案時，專案目錄會被視為方案目錄，這可能會導致還原專案與方案的行為差異。
User	Windows：`%appdata%\NuGet\NuGet.Config` Mac/Linux：`~/.config/NuGet/NuGet.Config` 或 `~/.nuget/NuGet/NuGet.Config` （因工具而異）所有平臺上都支援其他設定。工具無法編輯這些設定。 Windows：`%appdata%\NuGet\config\.Config` Mac/Linux：`~/.config/NuGet/config/.config` 或 `~/.nuget/config/*.config`	設定適用於所有作業，但會由任何解決方案層級設定覆寫。
電腦	Windows：`%ProgramFiles(x86)%\NuGet\Config` Mac/Linux：`/etc/opt/NuGet/Config` （Linux）或 `/Library/Application Support` （Mac）預設為。如果 `$NUGET_COMMON_APPLICATION_DATA` 不是 null 或空白，則 `$NUGET_COMMON_APPLICATION_DATA/NuGet/Config` 改為	設定套用至計算機上的所有作業，但會由任何使用者或解決方案層級設定覆寫。

注意

在 Mac/Linux 上，使用者組態檔位置會因工具而異。 .NET CLI 使用 ~/.nuget/NuGet 資料夾，而Mono則使用 ~/.config/NuGet 資料夾。

在 Mac/Linux 上，用戶層級配置檔位置會因工具而異

在 Mac/Linux 上，使用者組態檔位置會因工具而異。大部分的使用者都使用尋找資料夾下 ~/.nuget/NuGet 用戶組態檔的工具。這些其他工具會在資料夾下 ~/.config/NuGet 尋找使用者群組態檔：

Mono
NuGet.exe
Visual Studio 2019 for Mac （和舊版）
Visual Studio 2022 for Mac（和更新版本），只有在處理傳統Mono專案時。

如果您使用的工具牽涉到這兩個位置，請考慮遵循下列步驟來合併它們，讓您只能使用一個使用者層級組態檔：

檢查兩個用戶層級組態檔的內容，並將您想要的內容保留在資料夾下 ~/.nuget/NuGet 。
標記符號連結從 ~/.nuget/NuGet 設定為 ~/.config/NuGet。例如，執行bash命令： ln -s ~/.nuget/NuGet ~/.config/NuGet。

舊版 NuGet 的注意事項：

NuGet 3.3 和更早版本使用整個方案設定的 .nuget 資料夾。 NuGet 3.4+ 中不會使用此資料夾。
針對 NuGet 2.6 到 3.x，Windows 上的電腦層級配置檔位於 %ProgramData%\NuGet\Config[\{IDE}[\{Version}[\{SKU}]]]\NuGet.Config，其中 {IDE} 可以是 VisualStudio，{Version}是、或 Enterprise等{SKU}Community14.0ProVisual Studio 版本。若要將設定移至 NuGet 4.0+，只需將組態檔 %ProgramFiles(x86)%\NuGet\Config複製到。在 Linux 上，這個先前的位置是 /etc/opt，在 Mac 上則 /Library/Application Support為。

變更組態設定

NuGet.Config 檔案是包含索引鍵/值組的簡單 XML 文字檔，如 NuGet 組態設定主題中所述。

設定是使用 NuGet CLI config 命令進行管理：

預設會變更使用者層級組態檔。（在 Mac/Linux 上，使用者層級設定檔的位置因工具而異）
若要變更不同檔案中的設定，請使用 -configFile 參數。在此情況下，檔案可以使用任何檔案名稱。
索引鍵一定要區分大小寫。
需要提高權限，才能在電腦層級設定檔中變更設定。

警告

雖然您可以在任何文字編輯器中修改檔案，但是如果組態檔包含格式不正確的 XML (標記不成對、引號無效等等)，則 NuGet (v3.4.3 和更新版本) 會以無訊息方式忽略整個組態檔。這是偏好使用 nuget config 來管理設定的原因。

設定值

Windows：

# Set repositoryPath in the user-level config file
nuget config -set repositoryPath=c:\packages 

# Set repositoryPath in solution-level files
nuget config -set repositoryPath=c:\packages -configfile c:\my.Config
nuget config -set repositoryPath=c:\packages -configfile .\myApp\NuGet.Config

# Set repositoryPath in the computer-level file (requires elevation)
nuget config -set repositoryPath=c:\packages -configfile %ProgramFiles(x86)%\NuGet\Config\NuGet.Config

Mac/Linux：

# Set repositoryPath in the user-level config file
nuget config -set repositoryPath=/home/packages 

# Set repositoryPath in solution-level files
nuget config -set repositoryPath=/home/projects/packages -configfile /home/my.Config
nuget config -set repositoryPath=/home/packages -configfile home/myApp/NuGet.Config

# Set repositoryPath in the computer-level file (requires elevation)
nuget config -set repositoryPath=/home/packages -configfile $XDG_DATA_HOME/NuGet.Config

注意

在 NuGet 3.4 和更新版本中，您可以在任何值中使用環境變數，就像在 repositoryPath=%PACKAGEHOME% (Windows) 和 repositoryPath=$PACKAGEHOME (Mac/Linux) 中一樣。

移除值

若要移除值，請指定含空值的索引鍵。

# Windows
nuget config -set repositoryPath= -configfile c:\my.Config

# Mac/Linux
nuget config -set repositoryPath= -configfile /home/my.Config

建立新的組態檔

將下面的範本複製至新的檔案，然後使用 nuget config -configFile <filename> 來設定值：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
</configuration>

如何套用設定

多個 NuGet.Config 檔案可讓您將設定儲存在不同的位置，使其套用至單一解決方案或一組解決方案。這些設定會共同套用至從命令行或 Visual Studio 叫用的任何 NuGet 作業，這些設定會「最接近」解決方案或目前資料夾的優先順序。如果在項目檔上使用命令行工具，而不是方案檔，則專案目錄會當做「方案目錄」使用，當方案檔的子目錄中有 NuGet.Config 檔案時，可能會導致不一致的行為。

具體來說，NuGet 會依下列順序從不同的組態檔載入設定：

檔案NuGetDefaults.Config，其中包含僅與套件來源相關的設定。
電腦層級檔案。
使用者層級檔案。
使用 -configFile 所指定的檔案。
從磁碟驅動器根目錄到目前資料夾路徑中每個資料夾中找到的檔案（其中叫用， nuget.exe 或包含Visual Studio解決方案的資料夾）。例如，如果在中c:\A\B\C叫用命令，NuGet 會在中尋找並載入組態檔c:\，則c:\A為，c:\A\B\C最後c:\A\B為。

NuGet 在這些檔案中找到設定時，會如下套用設定：

針對單一項目的項目，NuGet 已取代相同索引鍵的任何先前找到的值。這表示「最接近」目前資料夾或解決方案的設定會覆寫稍早找到的任何其他設定。例如，如果任何其他組態檔中有 NuGetDefaults.Config 中的 defaultPushSource 設定，則會予以覆寫。
針對集合項目 (例如 <packageSources>)，NuGet 會將所有組態檔中的值結合成單一集合。
指定節點具有 <clear /> 時，NuGet 會忽略先前針對該節點所定義的組態值。

提示

nuget.config在方案存放庫的根目錄中新增檔案。這被視為最佳做法，因為它會提升可重複性，並確保不同的使用者具有相同的 NuGet 設定。

設定逐步解說

假設您在兩個不同的磁碟機上具有下列資料夾結構：

disk_drive_1
    User
disk_drive_2
    Project1
        Source
    Project2
        Source
    tmp

則在下列位置中會有四個具有指定內容的 NuGet.Config 檔案 (此範例未包含電腦層級檔案，但其行為與使用者層級檔案類似)。

檔案 A。使用者層級檔案 (在 Windows 上為 %appdata%\NuGet\NuGet.Config，在 Mac/Linux 上則為 ~/.config/NuGet/NuGet.Config)：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <activePackageSource>
        <add key="NuGet official package source" value="https://api.nuget.org/v3/index.json" />
    </activePackageSource>
</configuration>

檔案 B. disk_drive_2/NuGet.Config：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <config>
        <add key="repositoryPath" value="disk_drive_2/tmp" />
    </config>
    <packageRestore>
        <add key="enabled" value="True" />
    </packageRestore>
</configuration>

檔案 C. disk_drive_2/Project1/NuGet.Config：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <config>
        <add key="repositoryPath" value="External/Packages" />
        <add key="defaultPushSource" value="https://MyPrivateRepo/ES/api/v2/package" />
    </config>
    <packageSources>
        <clear /> <!-- ensure only the sources defined below are used -->
        <add key="MyPrivateRepo - ES" value="https://MyPrivateRepo/ES/nuget" />
    </packageSources>
</configuration>

檔案 D. disk_drive_2/Project2/NuGet.Config：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <packageSources>
        <!-- Add this repository to the list of available repositories -->
        <add key="MyPrivateRepo - DQ" value="https://MyPrivateRepo/DQ/nuget" />
    </packageSources>
</configuration>

NuGet 接著會如下載入並套用設定，視其叫用位置而定：

從 disk_drive_1/users叫用：只會使用用戶層級組態檔（A）中列出的預設存放庫，因為這是在上 disk_drive_1找到的唯一檔案。
從 disk_drive_2/ 或 disk_drive_/tmp叫用：先載入用戶層級檔案（A），然後 NuGet 會移至的 disk_drive_2 根目錄，並尋找檔案（B）。 NuGet 也會在中 /tmp 尋找組態檔，但找不到組態檔。因此，會使用上的 nuget.org 預設存放庫、啟用套件還原，並在中 disk_drive_2/tmp展開封裝。
從 disk_drive_2/Project1 或 disk_drive_2/Project1/Source叫用：先載入用戶層級檔案（A），然後 NuGet 會從的根 disk_drive_2載入檔案（B），後面接著檔案（C）。設定在（C）中覆寫（B）和（A）中的套件，因此repositoryPath安裝套件的位置不是 disk_drive_2/Project1/External/Packagesdisk_drive_2/tmp。此外，因為 (C) 會清除 <packageSources>，所以 nuget.org 不再是來源，並且只留下 https://MyPrivateRepo/ES/nuget。
從 disk_drive_2/Project2 或 disk_drive_2/Project2/Source叫用：用戶層級檔案（A）會先載入，後面接著檔案（B）和檔案（D）。因為未清除 packageSources，所以 nuget.org 和 https://MyPrivateRepo/DQ/nuget 都可以當成來源使用。套件會在中展開 disk_drive_2/tmp ，如（B）中所指定。

其他用戶範圍設定

從 5.7 開始，NuGet 已新增對其他使用者寬組態檔的支援。這可讓第三方廠商在不提高許可權的情況下新增其他使用者組態檔。這些組態檔位於子資料夾內的 config 標準用戶寬組態資料夾中。所有以 .config 或 .Config 結尾的檔案都會被視為。標準工具無法編輯這些檔案。

OS 平台	其他組態
Windows	`%appdata%\NuGet\config\*.Config`
Mac/Linux	`~/.config/NuGet/config/.config` 或 `~/.nuget/config/.config`

NuGet 預設檔案

NuGetDefaults.Config 檔案的存在是要指定從中安裝和更新套件的套件來源，以及使用 nuget push 控制用於發行套件的預設目標。系統管理員可以輕鬆地 (例如，使用群組原則) 將一致的 NuGetDefaults.Config 檔案部署至開發人員並建置電腦，因此可以確保組織中的所有人都會使用正確的套件來源，而非 nuget.org。

重要

NuGetDefaults.Config 檔案永遠不會導致從開發人員的 NuGet 組織移除套件來源。這表示，如果開發人員已經使用 NuGet，因此已註冊 nuget.org 套件來源，則在建立 NuGetDefaults.Config 檔案之後不會予以移除。

此外，NuGet 中的任何其他機制都無法 NuGetDefaults.Config 防止存取套件來源，例如 nuget.org。如果組織想要封鎖這類存取，則必須使用其他方式，例如防火牆來執行此動作。

`NuGetDefaults.Config` 位置

下表描述 NuGetDefaults.Config 檔案應儲存的位置，視目標 OS 而定：

OS 平台	`NuGetDefaults.Config` 位置
Windows	Visual Studio 2017 或 NuGet 4.x+：`%ProgramFiles(x86)%\NuGet` Visual Studio 2015 及更早版本或 NuGet 3.x 及更早版本：`%PROGRAMDATA%\NuGet`
Mac/Linux	`$XDG_DATA_HOME` (一般為 `~/.local/share` 或 `/usr/local/share`，取決於 OS 發行版本)

NuGetDefaults.Config 設定

packageSources：此集合的意義與一般組態檔中的 packageSources 相同，並指定預設來源。使用 packages.config 管理格式來安裝或更新專案中的套件時，NuGet 會依序使用來源。對於使用 PackageReference 格式的專案，NuGet 首先使用本機來源，然後使用網路共用的來源，再使用 HTTP 來源，與組態檔中的順序無關。 NuGet 一律會略過還原作業的來源順序。
disabledPackageSources：這個集合在檔案中 NuGet.Config 也有相同的意義，其中每個受影響的來源都會以其名稱列出，以及指出 true/false 是否停用的值。這可讓來源名稱和 URL 保留在 packageSources 中，而不需要預設將它開啟。接著，個別開發人員可以在其他NuGet.Config檔案中將來源的值設定為 false ，而不需再次尋找正確的 URL，以重新啟用來源。這也適用於將組織的完整內部來源 URL 清單提供給開發人員，同時預設僅啟用個別小組的來源。
defaultPushSource：指定作業的默認目標 nuget push ，覆寫的內建預設值 nuget.org。管理員 istrators 可以部署此設定，以避免意外地將內部套件發佈至公用nuget.org，因為開發人員特別需要使用 nuget push -Source 發佈至 nuget.org。

NuGetDefaults.Config 範例和應用

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <!-- defaultPushSource key works like the 'defaultPushSource' key of NuGet.Config files. -->
    <!-- This can be used by administrators to prevent accidental publishing of packages to nuget.org. -->
    <config>
        <add key="defaultPushSource" value="https://contoso.com/packages/" />
    </config>

    <!-- Default Package Sources; works like the 'packageSources' section of NuGet.Config files. -->
    <!-- This collection cannot be deleted or modified but can be disabled/enabled by users. -->
    <packageSources>
        <add key="Contoso Package Source" value="https://contoso.com/packages/" />
        <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    </packageSources>

    <!-- Default Package Sources that are disabled by default. -->
    <!-- Works like the 'disabledPackageSources' section of NuGet.Config files. -->
    <!-- Sources cannot be modified or deleted either but can be enabled/disabled by users. -->
    <disabledPackageSources>
        <add key="nuget.org" value="true" />
    </disabledPackageSources>
</configuration>

常用的 NuGet 組態

組態檔位置和使用

在 Mac/Linux 上，用戶層級配置檔位置會因工具而異

變更組態設定

設定值

移除值

建立新的組態檔

如何套用設定

設定逐步解說

其他用戶範圍設定

NuGet 預設檔案

`NuGetDefaults.Config` 位置

NuGetDefaults.Config 設定

NuGetDefaults.Config 範例和應用

意見反應

意見反應

其他資源

常用的 NuGet 組態

組態檔位置和使用

在 Mac/Linux 上，用戶層級配置檔位置會因工具而異

變更組態設定

設定值

移除值

建立新的組態檔

如何套用設定

設定逐步解說

其他用戶範圍設定

NuGet 預設檔案

NuGetDefaults.Config 位置

NuGetDefaults.Config 設定

NuGetDefaults.Config 範例和應用

意見反應

意見反應

其他資源

`NuGetDefaults.Config` 位置