常用的 NuGet 組態

NuGet 行為是透過可存在於專案、使用者和整個電腦層級的一或多個 NuGet.Config (XML) 檔案中的累積設定來驅動。 全域 NuGetDefaults.Config 檔案還會特別設定套件來源。 設定適用於 CLI、套件管理員主控台和套件管理員 UI 中發出的所有命令。

組態檔位置和使用

影響範圍 NuGet.Config 檔案位置 描述
解決方法 目前的資料夾 (也稱為解決方案資料夾) 或最高到磁碟機根目錄的任何資料夾。 在解決方案資料夾中,設定會套用到子資料夾中的所有專案。 請注意,若設定檔放在專案資料夾中,它對於該專案沒有任何影響。
User 窗戶:%appdata%\NuGet\NuGet.Config
Mac/Linux:~/.config/NuGet/NuGet.Config~/.nuget/NuGet/NuGet.Config (會因工具) 而有所不同
所有平臺上都支援其他設定。 工具無法編輯這些設定。
窗戶:%appdata%\NuGet\config\*.Config
Mac/Linux:~/.config/NuGet/config/*.config~/.nuget/config/*.config
設定適用於所有作業,但會覆寫為任何專案層級設定。
電腦 窗戶:%ProgramFiles(x86)%\NuGet\Config
Mac/Linux:$XDG_DATA_HOME 。 如果 $XDG_DATA_HOME 為 Null 或空白,則會使用 ~/.local/share/usr/local/share (依 OS 發行版本而異)
設定適用於電腦上的所有作業,但會覆寫為任何使用者或專案層級設定。

注意

在 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 (和舊版)
  • 只有在處理傳統 Mono 專案時,Visual Studio 2022 for Mac (和更新版本才會) 。

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

  1. 檢查兩個使用者層級組態檔的內容,並將您想要的內容保留在資料夾下 ~/.nuget/NuGet
  2. 將 符號連結從 ~/.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} 可以是 ,是 、 {Version} 等 Visual Studio 版本 14.0 ,且 {SKU}VisualStudioCommunityProEnterprise 。 若要將設定移轉至 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 project-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 project-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 會依下列順序從不同的組態檔載入設定:

  1. 檔案NuGetDefaults.Config其中包含只與套件來源相關的設定。
  2. 電腦層級檔案。
  3. 使用者層級檔案。
  4. 使用 -configFile 所指定的檔案。
  5. 從磁片磁碟機根目錄到目前資料夾 (路徑中,找到的檔案 (, nuget.exe 或包含 Visual Studio 專案的資料夾) 。 例如,如果在 中 c:\A\B\C 叫用命令,NuGet 會在 中尋找並載入組態檔 c:\ ,然後在 c:\A 、、 和 c:\A\B 最後 c:\A\B\C 尋找 。

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

  1. 針對單一項目的項目,NuGet 已取代相同索引鍵的任何先前找到的值。 這表示「最接近」目前資料夾或專案的設定會覆寫任何其他稍早找到的設定。 例如,如果任何其他組態檔中有 NuGetDefaults.Config 中的 defaultPushSource 設定,則會予以覆寫。
  2. 針對集合項目 (例如 <packageSources>),NuGet 會將所有組態檔中的值結合成單一集合。
  3. 指定節點具有 <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/Project1disk_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/Project2disk_drive_2/Project2/Source用:先載入 A) 的使用者層級 (檔案,再載入檔案 (B) 和檔案 (D) 。 因為未清除 packageSources,所以 nuget.orghttps://MyPrivateRepo/DQ/nuget 都可以當成來源使用。 封裝會依照 B) (中指定的方式展開 disk_drive_2/tmp

其他全使用者設定

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

作業系統平台 其他組態
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 而定:

作業系統平台 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 。 系統管理員可以部署此設定,以避免意外將內部套件發佈至公用 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>