常见的 NuGet 配置Common NuGet configurations

NuGet 的行为由一个或多个 NuGet.Config (XML) 文件(可存在于项目范围、用户范围和计算机范围的级别)中的累积设置驱动。NuGet's behavior is driven by the accumulated settings in one or more NuGet.Config (XML) files that can exist at project-, user-, and computer-wide levels. 还可以使用全局 NuGetDefaults.Config 文件专门配置包源。A global NuGetDefaults.Config file also specifically configures package sources. 这些设置应用于 CLI、包管理器控制台和包管理器 UI 中发出的所有命令。Settings apply to all commands issued in the CLI, the Package Manager Console, and the Package Manager UI.

配置文件的位置和使用Config file locations and uses

范围Scope NuGet.Config 文件的位置NuGet.Config file location 说明Description
解决方案Solution 当前文件夹(又称解决方案文件夹)或上至驱动器根目录的任何文件夹。Current folder (aka Solution folder) or any folder up to the drive root. 在解决方案文件夹中,设置应用于子文件夹中的所有项目。In a solution folder, settings apply to all projects in subfolders. 请注意,如果配置文件位于项目文件夹中,则对该项目没有任何影响。Note that if a config file is placed in a project folder, it has no effect on that project.
用户User Windows:%appdata%\NuGet\NuGet.ConfigWindows: %appdata%\NuGet\NuGet.Config
Mac/Linux:~/.config/NuGet/NuGet.Config~/.nuget/NuGet/NuGet.Config(因 OS 版本而异)Mac/Linux: ~/.config/NuGet/NuGet.Config or ~/.nuget/NuGet/NuGet.Config (varies by OS distribution)
设置应用于所有操作,但可被任何项目级的设置替代。Settings apply to all operations, but are overridden by any project-level settings.
计算机Computer Windows:%ProgramFiles(x86)%\NuGet\ConfigWindows: %ProgramFiles(x86)%\NuGet\Config
Mac/Linux:$XDG_DATA_HOMEMac/Linux: $XDG_DATA_HOME. 如果 $XDG_DATA_HOME 的值是 null 或为空,将使用 ~/.local/share/usr/local/share(因 OS 版本而异)If $XDG_DATA_HOME is null or empty, ~/.local/share or /usr/local/share will be used (varies by OS distribution)
设置虽然适用于计算机上的所有操作,但会被任何用户级或项目级设置覆盖。Settings apply to all operations on the computer, but are overridden by any user- or project-level settings.

针对早期版本的 NuGet 的说明:Notes for earlier versions of NuGet:

  • NuGet 3.3 及更早版本使用 .nuget 文件夹作为解决方案范围的设置。NuGet 3.3 and earlier used a .nuget folder for solution-wide settings. NuGet 3.4+ 中不使用此文件。This file is not used in 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 。For NuGet 2.6 to 3.x, the computer-level config file on Windows was located in %ProgramData%\NuGet\Config[\{IDE}[\{Version}[\{SKU}]]]\NuGet.Config, where {IDE} can be VisualStudio, {Version} was the Visual Studio version such as 14.0, and {SKU} is either Community, Pro, or Enterprise. 若要将设置迁移到 NuGet 4.0+,只需将配置文件复制到 %ProgramFiles(x86)%\NuGet\Config 即可。在 Linux 上,此位置以前为 /etc/opt;在 Mac 上为 /Library/Application Support。To migrate settings to NuGet 4.0+, simply copy the config file to %ProgramFiles(x86)%\NuGet\Config. On Linux, this previous location was /etc/opt, and on Mac, /Library/Application Support.

更改配置设置Changing config settings

NuGet.Config 文件是包含键/值对的简单 XML 文本文件,请参阅 NuGet 配置设置主题。A NuGet.Config file is a simple XML text file containing key/value pairs as described in the NuGet Configuration Settings topic.

设置通过 NuGet CLI config 命令进行管理:Settings are managed using the NuGet CLI config command:

  • 默认情况下需更改用户级配置文件。By default, changes are made to the user-level config file.
  • 若要更改其他文件中的设置,请使用 -configFile 开关。To change settings in a different file, use the -configFile switch. 在此情况下,文件可以使用任何文件名。In this case files can use any filename.
  • 键始终需要区分大小写。Keys are always case sensitive.
  • 更改计算机级设置文件中的设置需要提升权限。Elevation is required to change settings in the computer-level settings file.

警告

尽管可以修改任何文本编辑器中的文件,但如果配置文件中包含格式不正确的 XML(不匹配的标记、无效引号等),NuGet(v3.4.3 及更高版本)将以无提示方式忽略整个配置文件。Although you can modify the file in any text editor, NuGet (v3.4.3 and later) silently ignores the entire configuration file if it contains malformed XML (mismatched tags, invalid quotation marks, etc.). 因此推荐使用 nuget config 管理设置。This is why it's preferable to manage setting using nuget config.

设置值Setting a value

Windows: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: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) 中类似。In NuGet 3.4 and later you can use environment variables in any value, as in repositoryPath=%PACKAGEHOME% (Windows) and repositoryPath=$PACKAGEHOME (Mac/Linux).

删除值Removing a value

若要删除值,请指定具有空值的键。To remove a value, specify a key with an empty value.

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

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

创建新配置文件Creating a new config file

将下方的模板复制到新文件中,然后使用 nuget config -configFile <filename> 设置值:Copy the template below into the new file and then use nuget config -configFile <filename> to set values:

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

如何应用设置How settings are applied

可使用多个 NuGet.Config 文件在不同位置存储设置,以便设置可应用于单个项目、一组项目或所有项目。Multiple NuGet.Config files allow you to store settings in different locations so that they apply to a single project, a group of projects, or all projects. 这些设置共同应用于从命令行或 Visual Studio 调用的任何 NuGet 操作,并且优先应用“最靠近”项目或当前文件夹的设置。These settings collectively apply to any NuGet operation invoked from the command line or from Visual Studio, with settings that exist "closest" to a project or the current folder taking precedence.

具体而言,NuGet 将按照以下顺序从不同配置文件加载设置:Specifically, NuGet loads settings from the different config files in the following order:

  1. NuGetDefaults.Config 文件,仅包含与包源相关的设置。The NuGetDefaults.Config file, which contains settings related only to package sources.
  2. 计算机级文件。The computer-level file.
  3. 用户级文件。The user-level file.
  4. -configFile 指定的文件。The file specified with -configFile.
  5. 按照从驱动器根目录到当前文件夹(在此文件夹中调用 nuget.exe 或此文件夹包含 Visual Studio 项目)的路径,在其中的每个文件夹中找到的文件。Files found in every folder in the path from the drive root to the current folder (where nuget.exe is invoked or the folder containing the Visual Studio project). 例如,如果在 c:\A\B\C 中调用命令,NuGet 将先后查找并加载 c:,、c:\A、c:\A\B 和 c:\A\B\C 中的配置文件。For example, if a command is invoked in c:\A\B\C, NuGet looks for and loads config files in c:, then c:\A, then c:\A\B, and finally c:\A\B\C.

NuGet 在这些文件中找到设置时,设置将按如下方式应用:As NuGet finds settings in these files, they are applied as follows:

  1. 对于单项元素,NuGet 将替换以前找到的具有相同键的值。For single-item elements, NuGet replaced any previously-found value for the same key. 也就是说,“最靠近”当前文件夹或项目的设置将替代之前找到的任何其他设置。This means that settings that are "closest" to the current folder or project override any others found earlier. 例如,如果 NuGetDefaults.Config 中的 defaultPushSource 设置存在于任何其他配置文件中,则此设置将被替代。For example, the defaultPushSource setting in NuGetDefaults.Config is overridden if it exists in any other config file.

  2. 对于集合元素(如 <packageSources>),NuGet 会将所有配置文件中的值合并到一个集合中。For collection elements (such as <packageSources>), NuGet combines the values from all configuration files into a single collection.

  3. 当给定节点中存在 <clear /> 时,NuGet 将忽略之前为该节点定义的配置值。When <clear /> is present for a given node, NuGet ignores previously defined configuration values for that node.

设置演练Settings walkthrough

假设两个独立的驱动器上具有以下文件夹结构:Let's say you have the following folder structure on two separate drives:

disk_drive_1
    User
disk_drive_2
   Project1
     Source
   Project2
     Source
   tmp

随后以下位置上将有 4 个具有给定内容的 NuGet.Config 文件。You then have four NuGet.Config files in the following locations with the given content. (此示例不包括计算机级文件,但其与用户级文件具有相似行为。)(The computer-level file is not included in this example, but would behave similarly to the user-level file.)

文件 A. 用户级文件(Windows 上为 %appdata%\NuGet\NuGet.Config,Mac/Linux 上为 ~/.config/NuGet/NuGet.Config):File A. User-level file, (%appdata%\NuGet\NuGet.Config on Windows, ~/.config/NuGet/NuGet.Config on Mac/Linux):

<?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:File 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:File 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:File 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 将按如下方式加载和应用设置,具体取决于调用设置的位置:NuGet then loads and applies settings as follows, depending on where it's invoked:

  • 从 disk_drive_1/users 调用:仅使用用户级配置文件 (A) 中列出的默认存储库,因为这是 disk_drive_1 中的唯一文件。Invoked from disk_drive_1/users: Only the default repository listed in the user-level configuration file (A) is used, because that's the only file found on disk_drive_1.

  • 从 disk_drive_2/ 或 disk_drive_/tmp 调用:首先加载用户级文件 (A),然后 NuGet 转到 disk_drive_2 的根目录并查找文件 (B)。Invoked from disk_drive_2/ or disk_drive_/tmp: The user-level file (A) is loaded first, then NuGet goes to the root of disk_drive_2 and finds file (B). NuGet 还将在 /tmp 中查找配置文件,但不会找到此类文件。NuGet also looks for a configuration file in /tmp but does not find one. 因此,此时将使用 nuget.org 上的默认存储库、启用包还原并在 disk_drive_2/tmp 中展开包。As a result, the default repository on nuget.org is used, package restore is enabled, and packages get expanded in disk_drive_2/tmp.

  • 从 disk_drive_2/Project1 或 disk_drive_2/Project1/Source 调用:首先加载用户级文件 (A),然后 NuGet 从 disk_drive_2 的根目录依次加载文件 (B) 和文件 (C)。Invoked from disk_drive_2/Project1 or disk_drive_2/Project1/Source: The user-level file (A) is loaded first, then NuGet loads file (B) from the root of disk_drive_2, followed by file (C). (C) 中的设置会替代 (B) 和 (A) 中的设置,因此安装包的 repositoryPath 将为 disk_drive_2/Project1/External/Packages,而非 disk_drive_2/tmp 。Settings in (C) override those in (B) and (A), so the repositoryPath where packages get installed is disk_drive_2/Project1/External/Packages instead of disk_drive_2/tmp. 此外,由于 (C) 清除了 <packageSources>,因此 nuget.org 将不再可用作源,并仅留下 https://MyPrivateRepo/ES/nugetAlso, because (C) clears <packageSources>, nuget.org is no longer available as a source leaving only https://MyPrivateRepo/ES/nuget.

  • 从 disk_drive_2/Project2 或 disk_drive_2/Project2/Source 调用:首先加载用户级文件 (A),然后依次加载文件 (B) 和文件 (D)。Invoked from disk_drive_2/Project2 or disk_drive_2/Project2/Source: The user-level file (A) is loaded first followed by file (B) and file (D). 由于未清除 packageSources,因此 nuget.orghttps://MyPrivateRepo/DQ/nuget 都可用作源。Because packageSources is not cleared, both nuget.org and https://MyPrivateRepo/DQ/nuget are available as sources. 按 (B) 中的指定,包将在 disk_drive_2/tmp 中展开。Packages get expanded in disk_drive_2/tmp as specified in (B).

NuGet 默认文件NuGet defaults file

NuGetDefaults.Config 文件用于指定通过其安装和更新包的包源,以及控制使用 nuget push 发布包的默认目标。The NuGetDefaults.Config file exists to specify package sources from which packages are installed and updated, and to control the default target for publishing packages with nuget push. 由于管理员可以便捷地向开发人员和生成计算机部署一致的 NuGetDefaults.Config 文件(例如,使用组策略),因此他们可以确保组织中的每个人都在使用正确的包源,而不是 nuget.org。Because administrators can conveniently (using Group Policy, for example) deploy consistent NuGetDefaults.Config files to developer and build machines, they can ensure that everyone in the organization is using the correct package sources rather than nuget.org.

重要

NuGetDefaults.Config 文件绝不会导致开发人员 NuGet 配置中的包源被删除。The NuGetDefaults.Config file never causes a package source to be removed from a developer's NuGet configuration. 也就是说,如果开发人员已使用 NuGet,即意味着已注册 nuget.org 包源,创建 NuGetDefaults.Config 文件后将不会删除此包源。That means if the developer has already used NuGet and therefore has the nuget.org package source registered, it won't be removed after the creation of a NuGetDefaults.Config file.

此外,NuGet 中的 NuGetDefaults.Config 或任何其他机制都不会阻止访问 nuget.org 等包源。如果组织希望阻止此类访问,则必须通过其他方式(如防火墙)实现。Furthermore, neither NuGetDefaults.Config nor any other mechanism in NuGet can prevent access to package sources like nuget.org. If an organization wishes to block such access, it must use other means such as firewalls to do so.

NuGetDefaults.Config 的位置NuGetDefaults.Config location

下表根据目标操作系统描述 NuGetDefaults.Config 文件应存储的位置:The following table describes where the NuGetDefaults.Config file should be stored, depending on the target OS:

操作系统平台OS Platform NuGetDefaults.Config 的位置NuGetDefaults.Config Location
WindowsWindows Visual Studio 2017 或 NuGet 4.x+: %ProgramFiles(x86)%\NuGet\ConfigVisual Studio 2017 or NuGet 4.x+: %ProgramFiles(x86)%\NuGet\Config
Visual Studio 2015 及更低版本或 NuGet 3.x 及更低版本: %PROGRAMDATA%\NuGetVisual Studio 2015 and earlier or NuGet 3.x and earlier: %PROGRAMDATA%\NuGet
Mac/LinuxMac/Linux $XDG_DATA_HOME(通常为 ~/.local/share/usr/local/share,具体视 OS 版本而定)$XDG_DATA_HOME (typically ~/.local/share or /usr/local/share, depending on OS distribution)

NuGetDefaults.Config 的设置NuGetDefaults.Config settings

  • packageSources:此集合与常规配置文件中的 packageSources 具有相同含义,并可指定默认源。packageSources: this collection has the same meaning as packageSources in regular config files and specifies the default sources. 在使用 packages.config 管理格式的项目中安装或更新包时,NuGet 会按顺序使用源。NuGet uses the sources in order when installing or updating packages in projects using the packages.config management format. 对于使用 PackageReference 格式的项目,NuGet 会先使用本地源,再使用网络共享上的源,最后使用 HTTP 源,而不管配置文件中的顺序如何。For projects using the PackageReference format, NuGet uses local sources first, then sources on network shares, then HTTP sources, regardless of the order in the configuration files. NuGet 会始终忽略还原操作的源顺序。NuGet always ignores the order of sources with restore operations.

  • disabledPackageSources:此集合还与在 NuGet.Config 文件中时具有相同含义,集合中将列出每个受影响源的名称,并用 true/false 值指示源是否已禁用。disabledPackageSources: this collection also has the same meaning as in NuGet.Config files, where each affected source is listed by its name and a true/false value indicating whether it's disabled. 这可使源名称和 URL 保留在 packageSources 中,但不会将其默认打开。This allows the source name and URL to remain in packageSources without having it turned on by default. 开发人员随后可在其他 NuGet.Config 文件中将源的值设置为 false,以便重新启用源,而无需再次寻找正确的 URL。Individual developers can then re-enable the source by setting the source's value to false in other NuGet.Config files without having to find the correct URL again. 开发人员还可通过此方法获取组织的内部源 URL 完整列表,同时仅默认启用一个团队的源。This is also useful to supply developers with a full list of internal source URLs for an organization while enabling only an individual team's source by default.

  • defaultPushSource:指定 nuget push 操作的默认目标,同时替代 nuget.org 的内置默认值。管理员可部署此设置以避免误将内部包发布到公共 nuget.org,因为开发人员专门负责使用 nuget push -Source 向 nuget.org 发布。defaultPushSource: specifies the default target for nuget push operations, overriding the built-in default of nuget.org. Administrators can deploy this setting to avoid publishing internal packages to the public nuget.org by accident, as developers specifically need to use nuget push -Source to publish to nuget.org.

示例 NuGetDefaults.Config 和应用程序Example NuGetDefaults.Config and application

<?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>