常见的 NuGet 配置

项目
02/01/2024

NuGet 的行为受一个或多个 NuGet.Config (XML) 文件中累积设置驱动，这些文件可以存在于解决方案（如果不使用解决方案，则存在项目）、用户和计算机级别。还可以使用全局 NuGetDefaults.Config 文件专门配置包源。这些设置应用于 CLI、包管理器控制台和包管理器 UI 中发出的所有命令。

配置文件的位置和使用

范围	`NuGet.Config` 文件位置	说明
解决方案	当前文件夹（又称解决方案文件夹）或上至驱动器根目录的任何文件夹。	在解决方案文件夹中，设置应用于子文件夹中的所有项目。请注意，如果配置文件位于项目文件夹中，则对该项目没有任何影响。在命令行上还原项目时，项目的目录被视为解决方案目录，这可能会导致还原项目与解决方案时的行为差异。
用户	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（及更早版本）
仅当处理经典 Mono 项目时，使用 Visual Studio 2022 for Mac（及更高版本）。

如果使用的工具涉及这两个位置，请考虑按照以下步骤合并它们，以便仅使用一个用户级配置文件：

检查两个用户级配置文件的内容，并将所需的配置文件保留在 ~/.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} 是 Visual Studio 版本，例如 14.0，以及 {SKU} 是 Community、Pro 或 Enterprise）。若要将设置迁移到 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:\A\B\C。

NuGet 在这些文件中找到设置时，设置将按如下方式应用：

对于单项元素，NuGet 将替换以前找到的具有相同键的值。也就是说，“最靠近”当前文件夹或解决方案的设置将替代之前找到的任何其他设置。例如，如果 NuGetDefaults.Config 中的 defaultPushSource 设置存在于任何其他配置文件中，则此设置将被替代。
对于集合元素（如 <packageSources>），NuGet 会将所有配置文件中的值合并到一个集合中。
当给定节点中存在 <clear /> 时，NuGet 将忽略之前为该节点定义的配置值。

提示

在解决方案存储库的根目录中添加 nuget.config 文件。这被认为是一种最佳做法，因为它促进了可重复性，并可确保不同的用户具有相同的 NuGet 配置。

设置演练

假设两个独立的驱动器上具有以下文件夹结构：

disk_drive_1
    User
disk_drive_2
    Project1
        Source
    Project2
        Source
    tmp

随后以下位置上将有 4 个具有给定内容的 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/Packages，而非 disk_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 都可用作源。按 (B) 中的指定，包将在 disk_drive_2/tmp 中展开。

其他用户范围配置

从版本 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 文件后将不会删除此包源。

此外，无论 NuGetDefaults.Config 还是 NuGet 中的任何其他机制都无法阻止访问包源（如 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>

常见的 NuGet 配置

配置文件的位置和使用

在 Mac/Linux 上，用户级配置文件位置因工具而异

更改配置设置

设置值

删除值

创建新配置文件

如何应用设置

设置演练

其他用户范围配置

NuGet 默认文件

`NuGetDefaults.Config` 位置

NuGetDefaults.Config 的设置

示例 NuGetDefaults.Config 和应用程序

反馈

反馈

其他资源

常见的 NuGet 配置

配置文件的位置和使用

在 Mac/Linux 上，用户级配置文件位置因工具而异

更改配置设置

设置值

删除值

创建新配置文件

如何应用设置

设置演练

其他用户范围配置

NuGet 默认文件

NuGetDefaults.Config 位置

NuGetDefaults.Config 的设置

示例 NuGetDefaults.Config 和应用程序

反馈

反馈

其他资源

`NuGetDefaults.Config` 位置