常见的 NuGet 配置

NuGet 的行为由一个或多个配置（XML）文件中的累积设置驱动，这些文件可以存在于解决方案级别（若未使用解决方案则为项目级别）、用户级别和计算机级级别。

配置文件的位置和使用

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

在 Mac/Linux 上，用户配置文件位置因工具而异。 大多数用户使用查找文件夹下 ~/.nuget/NuGet 的用户配置文件的工具。 其他工具在 ~/.config/NuGet 文件夹下查找用户配置文件：

• Mono
• NuGet.exe
• Visual Studio 2019 for Mac（和早期版本）
• Visual Studio 2022 for Mac（及更高版本），仅在处理经典 Mono 项目时使用。

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

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} 可以是 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 配置命令管理设置：

• 默认情况下，对用户级配置文件进行更改。 （在 Mac/Linux 上，用户级配置文件的位置因工具而异）
• 若要更改其他文件中的设置，请使用 -configFile 开关。 在这种情况下，文件可以使用任何文件名。
• 键始终区分大小写。
• 需要权限提升才能更改计算机设置文件中的设置。

设置值

窗户：

# Set globalPackagesFolder in the user-level config file
dotnet nuget config set globalPackagesFolder "C:\packages"

# Set repositoryPath (available for packages.config only) in the user-level config file
dotnet nuget config set repositoryPath "C:\packages"

# Set repositoryPath in solution-level files
dotnet nuget config set repositoryPath "C:\packages" --configfile "C:\my.config"
dotnet nuget config set repositoryPath "c:\packages" --configfile "..\..\my.config"

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

Mac/Linux：

# Set globalPackagesFolder in the user-level config file
dotnet nuget config set globalPackagesFolder /home/packages

# Set repositoryPath (available for packages.config only) in the user-level config file
dotnet nuget config set repositoryPath /home/packages

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

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

删除值

若要删除值，请指定具有空值的键。

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

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

创建新的配置文件

使用 .NET CLI，通过运行 dotnet new nugetconfig创建默认 nuget.config。 有关详细信息，请参阅 dotnet CLI 命令。

或者，将以下模板手动复制到新文件中，然后使用 nuget config -configFile <filename> 设置值。

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

如何应用设置

多个 NuGet.Config 文件允许将设置存储在不同的位置，以便它们适用于单个解决方案或一组解决方案。 这些设置应用于从命令行或 Visual Studio 调用的任何 NuGet 操作，其中距解决方案或当前文件夹最近的设置具有优先级。 如果在项目文件（而不是解决方案文件）上使用命令行工具，则项目目录将用作“解决方案目录”，当解决方案文件的子目录中有 NuGet.Config 文件时，这可能会导致行为不一致。

具体而言，如果未在命令行上显式指定配置文件，NuGet 会按以下顺序从不同的配置文件加载设置：

1. （不常见）该文件NuGetDefaults.Config包含仅与包源相关的设置。
2. 计算机级文件。
3. 用户级文件。
4. 从驱动器根目录到当前文件夹（即调用 nuget.exe 或包含 Visual Studio 解决方案的文件夹）的路径中所有文件夹中找到的文件。 例如，如果在 c:\A\B\C 中调用命令，NuGet 会先在 c:\ 中查找并加载配置文件，然后依次在 c:\A、c:\A\B 和 c:\A\B\C 中查找配置文件。

在命令行上显式指定配置文件时，例如nuget -configFile my.config或dotnet restore --configfile my.config，将仅使用指定文件中的设置。

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

1. 对于单项元素，NuGet 替换了同一键之前找到的任何值。 这意味着，与当前文件夹或解决方案“最接近”的设置将替代先前找到的任何其他设置。 例如，如果NuGetDefaults.Config中的defaultPushSource设置存在于任何其他配置文件中，则该设置会被重写。
2. 对于集合元素（例如 <packageSources>），NuGet 将所有配置文件中的值合并到单个集合中。
3. 当给定节点中存在 <clear /> 时，NuGet 将忽略之前为该节点定义的配置值。

设置指南

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

disk_drive_1
    User
disk_drive_2
    Project1
        Source
    Project2
        Source
    tmp

然后，在以下位置有四 NuGet.Config 个包含给定内容的文件。 （此示例中不包括计算机级文件，但行为类似于用户级文件。

文件 A.用户级文件（%appdata%\NuGet\NuGet.Config 在 Windows 上、 ~/.config/NuGet/NuGet.Config Mac/Linux 上）：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="nuget" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
</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）中的设置，因此包的安装位置是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都可用作源。 包在 disk_drive_2/tmp 中按照 (B) 的指定进行展开。

其他用户范围配置

从 5.7 开始，NuGet 添加了对其他用户范围的配置文件的支持。 这允许第三方供应商在不提升的情况下添加其他用户配置文件。 这些配置文件位于子文件夹中的标准用户范围配置文件夹中 config 。 以.config或.Config结尾的所有文件都将被考虑。 标准工具无法编辑这些文件。

NuGet 默认文件

可以指定用于安装和更新包的包源或者控制包发布的默认目标的 NuGetDefaults.Config 并不常见，这些特定功能仅限于 nuget push。

由于管理员可以方便地（例如使用组策略）将一致的 NuGetDefaults.Config 文件部署到开发人员和生成计算机，因此他们可以确保组织中的每个人都使用一致的包源，无论是否包括 nuget.org。

NuGetDefaults.Config 位置

下表描述了应存储文件的位置 NuGetDefaults.Config ，具体取决于目标 OS：

NuGetDefaults.Config 设置

• packageSources：此集合的含义与 packageSources 常规配置文件中的含义相同，并指定默认源。 NuGet 在项目中使用packages.config管理格式安装或更新包时，会按顺序使用源。 对于使用 PackageReference 格式的项目，NuGet 首先使用本地源，然后是网络共享上的源，然后是 HTTP 源，而不考虑配置文件中的顺序。 NuGet 始终忽略在还原操作中源的顺序。

• disabledPackageSources：此集合的含义也与文件中 NuGet.Config 的含义相同，其中每个受影响的源都按其名称列出，以及一个 true/false 值，该值指示它是否被禁用。 这样，源名称和 URL 就可以保留在 packageSources 中，而无需默认启用它。 然后，单个开发人员可以通过将源的值设置为 false 其他 NuGet.Config 文件中来重新启用源，而无需再次找到正确的 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>