使用 NuGet 包还原功能恢复包

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

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

包还原行为

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

如果尚未安装所需的包，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>的项目，包存在于本地 全局包 文件夹中，并重新创建项目 obj/project.assets.json 文件。
对于使用 packages.config的项目，包将显示在项目的包文件夹中。
项目现在应成功构建。

如果项目文件或 packages.config 文件中的包引用不正确且与所需状态不匹配，请安装或更新正确的包，而不是使用包还原。

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

在 Visual Studio 中进行包还原

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

配置 Visual Studio 包还原选项

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

显示 NuGet 包管理器选项的屏幕截图。

允许 NuGet 下载缺少的包

选择 “允许 NuGet 下载缺少的包 ”以启用包还原和 “还原 NuGet 包 ”命令。此选择会在全局 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 中的全局 NuGet.Config 文件中，%ProgramData%\NuGet\Config，有时位于特定 <IDE>\Version<\><SKU> Visual Studio 文件夹下，或者在 ~/.local/share 的 Mac/Linux 中。然后，单个用户可以根据需要在项目级别选择性地启用还原。有关 NuGet 如何设置多个配置文件优先级的更多详细信息，请参阅通用 NuGet 配置。

重要

如果直接编辑 packageRestoreNuGet.Config 中的设置，请重启 Visual Studio，以便选项显示当前值。

在构建过程中自动检查缺少的包

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

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

必须在“选项”中选择“允许 NuGet 下载缺失的包”和“在 Visual Studio 构建时自动检查缺失的包”，以在构建期间启用包还原。

选择默认包管理格式

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

注释

如果项目不支持这两种包管理格式，则 NuGet 使用与项目兼容的包管理格式，这可能不是在选项中设置的默认格式。 NuGet 随后不会提示首次安装时选择，即使选择了该选项。
如果使用包管理器控制台在项目中安装第一个包，则 NuGet 不会提示选择格式，即使该选项在 “选项”中选择也是如此。

手动或自动恢复软件包

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

如果在 “选项”中启用了自动还原，则从模板创建项目或生成项目时，包还原会自动发生。对于 NuGet 4.0+，对 SDK 样式项目进行更改时，还原也会自动发生。

对于使用<PackageReference>的项目，可以在“依赖项包”下的 Visual Studio >中看到包引用。在 解决方案资源管理器中，那些在手动还原或运行生成时无法正确安装的包会显示错误图标。右键单击该项目，选择“ 管理 NuGet 包”，然后使用 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 包，该包也运行 restore。

使用 NuGet CLI 还原

NuGet CLI 还原命令下载并安装任何缺少的包。该命令适用于使用 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 包引用。

若要使用 MSBuild 恢复，请执行以下步骤：

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

注释

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

使用 Azure Pipelines 或 Azure DevOps Server 进行还原

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

如果使用 TFS 2013 或更高版本的团队生成模板，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 还原作使用本地 全局包 和 http 缓存 文件夹中的包，如管理全局包和缓存文件夹中所述。若要避免使用这些本地包，请使用以下选项。

清除所有本地缓存：

在 Visual Studio 中，选择“工具>>>”处的“清除所有 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 文件，该文件指定 globalPackagesFolderPackageReference 或指定 repositoryPathpackages.config 到另一个文件夹。有关详细信息，请参阅配置设置。
仅对于 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 的任何引用。

测试自动包还原：

从解决方案中删除包文件夹。
在 Visual Studio 中打开解决方案并启动生成。自动包还原应下载并安装每个依赖项包，而无需将其添加到源代码管理。

后续步骤

反馈

此页面是否有帮助？

Last updated on 2025-10-15