使用“NuGet 包还原”还原包

项目
11/30/2023

“NuGet 包还原”将还原项目文件或 packages.config 文件中列出的所有项目的依赖项。可以使用 nuget restore、dotnet restore 和 msbuild -t:restore 或通过 Visual Studio 手动还原包。命令 dotnet build 和 dotnet run 会自动还原包，可以将 Visual Studio 配置为在生成项目时自动还原包。

为了提升更清洁的开发环境并减少存储库大小，包还原使项目的所有依赖项都可用，而无需将它们存储在源代码管理中。要配置源代码管理存储库以排除包二进制文件，请参阅包和源代码管理。

包还原行为

包还原试图将所有包依赖项安装到与项目文件（如 .csproj）中的 <PackageReference> 或 packages.config 文件中的 <package> 相匹配的状态。程序包还原首先根据需要安装项目的直接依赖项，然后在整个依赖项关系图中安装这些包的所有依赖项。

如果尚未安装所需的包，NuGet 将首先尝试从本地全局包或 HTTP 缓存文件夹中检索包。如果包不在本地文件夹中，NuGet 将尝试从 Visual Studio 的“工具>”“选项>”“NuGet 包管理器>”“包源”下所有已配置源下载包。

在还原期间，NuGet 会忽略包源的顺序，并使用响应请求的第一个源的包。如果还原失败，则在检查所有源之后，NuGet 不会指示失败。之后，NuGet 仅会报告列表中最后一个源的失败。该错误意味着包在任何源上都不存在，即使它不会单独列出其他故障。

有关 NuGet 行为的详细信息，请参阅常见的 NuGet 配置。

还原包

若项目文件或 packages.config 文件中的包引用正确，则使用你的首选工具还原程序包：

Visual Studio
dotnet CLI
nuget.exe CLI
MSBuild
Azure Pipelines 或 Azure DevOps Server >>

成功还原后：

对于使用 <PackageReference> 的项目，包存在于本地 global-packages 文件夹中，并重新创建项目 obj/project.assets.json 文件。
对于使用 packages.config 的项目，包将显示在项目的“包”文件夹中。
该项目现在应能成功生成。

若项目文件或 packages.config 文件中的包引用不正确，与使用包还原时所需的状态不匹配，则需要安装或更新正确的包而非使用包还原。

如果在运行包还原后缺少包或出现与包相关的错误（如解决方案资源管理器中的错误图标），请按照包还原错误包还原错误疑难解答进行操作，或者重新安装或更新包。 Visual Studio 中的包管理器控制台提供了多个选项，用于重新安装包。有关详细信息，请参阅使用 Package-Update。

在 Visual Studio 中还原包

在 Windows 上的 Visual Studio 中，可以自动或手动还原包。首先，通过“工具>”“选项>”“NuGet 包管理器”配置包还原。

配置 Visual Studio 包还原选项

在“工具>”“选项>”“NuGet 包管理器>”“常规”下配置以下包还原选项。

Screenshot that shows the NuGet Package Manager options.

允许 NuGet 下载缺少的包

选择“允许 NuGet 下载缺少的包”以启用包还原和“还原 NuGet 包”命令。此选择将全局 NuGet.Config 文件的 packageRestore 部分中的 packageRestore/enabled 设置设置为 True，路径为 Windows 上的 %AppData%\Roaming\NuGet 或 Mac 或 Linux 上的 ~/.nuget/NuGet/。

<configuration>
    <packageRestore>
        <add key="enabled" value="True" />
    </packageRestore>
</configuration>

注意

要全局重写 packageRestore/enabled 设置，可在打开 Visual Studio 或启动生成之前，将 EnableNuGetPackageRestore 环境变量设为 True 或 False 值。

若要启用或禁用计算机上所有用户的包还原，可以在 Windows 的 %ProgramData%\NuGet\Config 中将配置设置添加到全局 NuGet.Config 文件，有时位于特定 <IDE>\<版本>\<SKU> Visual Studio 文件夹下，或者在 Mac/Linux 的 ~/.local/share 中。然后，各个用户可以按照项目级别的要求有选择地启用还原。有关 NuGet 如何设置多个配置文件优先级的详细信息，请参阅常见 NuGet 配置。

重要

如果直接在 NuGet.Config 中编辑 packageRestore 设置，请重启 Visual Studio，以便“选项”中显示当前值。

在生成过程中自动为缺少的包检查

选择“在 Visual Studio 中生成期间自动检查缺少的包”，以便在从 Visual Studio 运行生成时自动还原任何缺失的包。此设置不会影响从 MSBuild 命令行运行的生成。此选择将 NuGet.Config 文件 packageRestore 部分中的 packageRestore/automatic 设置设置为 True。

<configuration>
    <packageRestore>
        <add key="automatic" value="True" />
    </packageRestore>
</configuration>

对于非 SDK 样式的项目，必须选择“允许 NuGet 下载缺失的包”，并在“选项”中的 Visual Studio 中生成期间自动检查缺少的包，才能启用自动还原。

选择默认包管理格式

NuGet 有两种包管理格式：PackageReference 和 packages.config。从“包管理”下的下拉列表中选择要使用的格式。还可以选择是否允许在第一次安装包时选择格式。

注意

如果这两种包管理格式均不受项目支持，则 NuGet 会使用与项目兼容的包管理格式，所用格式可能并非选项中的默认设置。这样，即使您选择了该选项，NuGet 也不会在首次安装时提示选择。
如果使用包管理器控制台在项目中安装首个包，则即使“选项”下已选中该选项，NuGet 也不会提示选择格式。

手动或自动还原包

在“选项”中启用包还原后，可以在解决方案资源管理器中右键单击解决方案，然后选择“还原 NuGet 包”以随时还原包。

如果在“选项”中启用了自动还原功能，则在从模板创建项目或构建项目时会自动进行“包还原”。对于 NuGet 4.0+，对 SDK 类型的项目进行更改时也会自动还原。

对于使用 <PackageReference> 的项目，可以在“依赖项>”“包”下的 Visual Studio 解决方案资源管理器中查看包引用。手动还原或运行解决方案资源管理器中的生成显示错误图标时无法正确安装的包。右键单击项目，并选择“管理 NuGet 包”，然后使用“包管理器”卸载并重新安装受影响的程序包。有关详细信息，请参阅重新安装和更新包。

如果看到错误“此项目引用此计算机上缺少的 NuGet 包”或者“一个或更多 NuGet 包需要还原但无法还原，因为未授予许可”，请确保你已启用自动还原。对于旧项目，请参阅迁移到自动程序包还原。另请参阅包还原错误疑难解答。

使用 dotnet CLI 进行还原

dotnet restore 命令将还原项目文件列出 <PackageReference> 的包。有关详细信息，请参阅项目文件中的 PackageReference。

.NET Core 2.0 和更高版本 dotnet build 和 dotnet run 命令自动还原包。从 NuGet 4.0 开始，dotnet restore 运行与 nuget restore 相同的代码。

通过 dotnet restore 还原包：

打开命令行并切换到包含项目文件的目录。
运行 dotnet restore。

重要

若要将缺少的程序包引用添加到项目文件，请使用 dotnet add package，它也会运行 restore。

使用 NuGet CLI 进行还原

NuGet CLI restore 命令下载并安装任何缺少的包。该命令适用于使用 PackageReference 或 packages.config 进行包引用的项目。

和 install 一样，restore 命令仅将包添加到磁盘，但不会修改项目文件或 packages.config。若要添加项目依赖项，请使用 Visual Studio 包管理器 UI 或控制台。

若要还原包，请运行以下命令：

nuget restore <projectPath>

该 restore 命令使用指定项目路径中的解决方案文件或 package.config 文件。

例如，若要还原当前目录中 MySolution.sln 的所有包，请运行：

nuget restore MySolution.sln

注意

对于使用 PackageReference 的非 SDK 样式项目，请改用 msbuild -t:restore 还原包。

使用 MSBuild 进行还原

可以使用 msbuild -t:restore 还原 NuGet 4.x+ 和 MSBuild 15.1+ 中的包，这些包包含在 Visual Studio 2017 及更高版本中。

此命令将还原使用 PackageReference 进行包引用的项目中的包。从 MSBuild 16.5+ 开始，当与 -p:RestorePackagesConfig=true 同时使用时，该命令还支持 package.config 包引用。

若要使用 MSBuild 还原：

通过搜索开发人员命令提示并从 Windows“开始”菜单启动提示来打开开发人员命令提示，该菜单配置 MSBuild 所需的所有路径。
切换到项目文件夹，然后输入 msbuild -t:restore。
还原完成后，输入 msbuild 以重新生成项目。确保 MSBuild 输出指示生成已成功完成。

注意

可用 msbuild -restore 运行 restore，重新加载项目并生成，因为生成是默认目标。有关详细信息，请参阅使用一个 MSBuild 命令还原和生成。

使用 Azure Pipelines 或 Azure DevOps Server 还原

在 Azure Pipelines 上创建生成定义时，你可以在任意生成任务前将 NuGet 还原或 dotnet CLI 还原任务包括在定义中。默认情况下，某些生成模板包括还原任务。

如果你使用 TFS 2013 或更高版本的 Team Build 模板，Azure DevOps Server 和 TFS 2013 及更高版本会在生成期间自动还原包。你还可以包含一个生成步骤来运行命令行还原选项，或者选择将生成模板迁移到更高版本。有关详细信息，请参阅使用 Team Foundation Build 设置包还原。

约束包版本

NuGet 通过任意方法还原包时，将遵守你在 packages.config 或项目文件中指定的任何版本约束。

在 packages.config 中，可以在依赖项中指定一个 allowedVersions 范围。有关更多信息，请参阅升级版本约束。例如：
```
<package id="Newtonsoft.json" version="6.0.4" allowedVersions="[6,7)" />
```
在项目文件中，可在依赖项的 Version 属性中指定版本范围。例如：
```
<PackageReference Include="Newtonsoft.json" Version="[6,7)" />
```

在两种情况下，都使用包版本控制中介绍的表示法。

强制从远程包源还原

默认情况下，NuGet 还原操作使用本地 global-packages 和 http-cache 文件夹中的包，如管理全局包和缓存文件夹中所述。若要避免使用这些本地包，请使用以下选项。

清除所有本地缓存：

在 Visual Studio 中，选择“工具>”“选项>”“NuGet 包管理器>”“常规”下的“清除所有 NuGet 缓存”按钮。
在 dotnet CLI 中使用 dotnet nuget locals all --clear。
在 NuGet CLI 中，使用 nuget locals all -clear。

要避免使用global-packages 文件夹中的包，请执行以下操作：

使用 nuget locals global-packages -clear 或 dotnet nuget locals global-packages --clear 清除文件夹。
将 NUGET_PACKAGES 环境变量暂时设置为其他文件夹。
在不同文件夹下创建一个 NuGet.Config 文件，该文件将 PackageReference 设置为 globalPackagesFolder，packages.config 设置为 repositoryPath。有关详细信息，请参阅配置设置。
仅限 MSBuild，请指定具有 RestorePackagesPath 属性的其他文件夹。

若要避免在 HTTP 缓存中使用包：

使用 nuget locals http-cache -clear 或 dotnet nuget locals http-cache --clear 清除缓存。
暂时将 NUGET_HTTP_CACHE_PATH 环境变量设置在其他文件夹。
对于 nuget restore，请使用 -NoHttpCache 选项，或者对于 dotnet restore，请使用 --no-http-cache 选项。这些选项不会影响通过 Visual Studio 包管理器或控制台执行的还原操作。

迁移到自动程序包还原

早期版本的 NuGet 支持 MSBuild 集成包还原。使用已弃用的集成 MSBuild 的包还原项目，应迁移到自动包还原。

这些项目通常包含内存三个文件的 .nuget 文件夹：NuGet.config、nuget.exe 和 NuGet.targets。 NuGet.targets 文件会导致 NuGet 使用 MSBuild 集成方法，因此必须将其删除。

要迁移到自动程序包还原，请执行以下操作：

启用自动包还原。
关闭 Visual Studio。
删除 .nuget/nuget.exe 和 .nuget/NuGet.targets。
对于每个项目文件，删除 <RestorePackages> 元素并删除对 NuGet.targets 的任何引用。

若要测试自动程序包还原，请执行以下操作：

删除解决方案中的“packages”文件夹。
在 Visual Studio 中打开解决方案并开始生成。自动程序包还原应下载并安装每个依赖包，而不将其添加到源代码管理中。

通过