PAYATHON 2026

.NET 8 MVC Area scaffolding 为何报“Package restore failed”?

排障赵师傅

结论

Package restore failed 是 scaffolding 返回的汇总错误。仅凭这条提示和现有 .csproj,还不能确定原因。先查看失败前的 NuGet 错误,确认代码生成器尝试安装的包及版本,以及还原失败的具体原因。

正常生成使用的是项目当前的依赖,scaffolding 则可能安装或更新代码生成所需的包。如果这一步失败并回滚,项目仍然可以使用原来的依赖成功生成。

现有信息也不足以判断 Microsoft.VisualStudio.Web.CodeGeneration.Design 8.0.0 与 EF Core 8.0.11 存在冲突。该代码生成包支持 net8.0,两个产品的补丁版本号不必完全一致,是否兼容取决于实际依赖约束。包版本信息

为什么手动还原成功,添加 Area 却失败?

NuGet Restore 根据项目声明的包引用解析依赖,不会自动验证代码生成器后续准备安装的所有包。NuGet 还原机制

日志中的这条信息说明,此次操作更改了包,并在失败后回滚:

Rolling back package changes for 'BookWeb'.

因此,失败后再运行 Restore,验证的可能已经是回滚后的依赖,而非导致失败的那组依赖。

反复删除 bin、obj 或清理 NuGet 缓存也未必有效。如果问题出在包版本约束、目标框架不兼容或包源配置,清理缓存不会改变这些条件。

同一解决方案中有 Razor Pages 项目,本身不足以说明存在冲突。应核对当前操作是否针对 BookWeb,以及共享配置或项目引用是否影响了依赖解析。

第一步:查看导致失败的 NuGet 错误

在 Visual Studio 中打开“视图 → 输出”,查看此次操作的包管理或代码生成输出。具体有哪些输出类别,取决于安装的组件和版本。

重新执行一次 Add → Area,保留从开始安装包到回滚结束的完整日志,重点检查:

  • 尝试安装或更新的包名、版本号。
  • 第一条 NuGet 错误及其依赖链。
  • 实际使用的包源。
  • 出错的项目是否为 BookWeb。

常见错误的排查方向如下:

错误 排查方向
NU1202 包不支持项目的目标框架,检查是否选入了不适用于 net8.0 的版本
NU1605 检测到包降级,根据日志中的依赖链调整直接引用
NU1101、NU1102 找不到包或所需版本,检查包源、版本是否存在及包源映射
NU1301 无法加载包源服务索引,检查日志中指定源的连接、代理和身份验证

错误码的含义可查阅 NuGet 错误参考。NU1605 属于警告,但 .NET SDK 默认会将它作为错误处理,不宜通过直接屏蔽它来完成生成。NU1605 说明

也可以在 BookWeb.csproj 所在目录打开 PowerShell,记录当前环境和还原结果:

dotnet --info
dotnet --list-sdks
dotnet list .\BookWeb.csproj package --include-transitive
dotnet restore .\BookWeb.csproj --force --verbosity diagnostic *> restore.log

--force 会重新解析依赖,诊断输出可用于查看还原过程。dotnet restore 参数说明

这份 restore.log 只反映执行命令时的项目状态。如果 Visual Studio 已经回滚包更改,它就不能替代 scaffolding 失败时的日志。

第二步:按日志调整依赖和环境

如果日志显示代码生成器正在引入不支持 net8.0 的包,就选择支持 .NET 8 的版本,避免直接把所有依赖升级到各自的“最新版本”。

出现包降级错误时,沿日志中的依赖链检查直接引用和传递依赖。调整这里列出的 EF Core 包时,应保持 Microsoft.EntityFrameworkCore、Microsoft.EntityFrameworkCore.SqlServer、Microsoft.EntityFrameworkCore.Tools 的版本一致;代码生成包则根据自身的依赖要求选择版本。

同时检查项目及其父目录中的以下配置:

  • global.json:是否固定了实际使用的 SDK。
  • Directory.Packages.props:是否集中控制包版本。
  • Directory.Build.props、Directory.Build.targets:是否设置了还原或警告策略。
  • NuGet.Config:是否配置了其他包源、身份验证或 packageSourceMapping。

即使可以访问 nuget.org,其他已启用的包源仍可能存在问题。

记录 Visual Studio 的完整版本号,比描述为“最新版本”更有助于复现问题。如果在同一 Visual Studio 版本下,新建的 MVC 项目也无法添加 Area,再检查 Visual Studio Installer 中的“ASP.NET 和 Web 开发”工作负载,并考虑更新或修复相关组件。

第三步:用命令行对照 Visual Studio 的结果

通过命令行生成,可以帮助判断问题是否集中在 Visual Studio 的集成流程。Visual Studio 自带 scaffolding 引擎,使用它进行 scaffolding 无需先安装全局 dotnet-aspnet-codegenerator。代码生成工具说明

下面以已发布的 8.0.7 作为 8.x 对照版本,目前尚未证实该版本能修复当前故障。工具版本、项目包版本

先保存当前更改,再在 MVC 项目目录执行:

# 仅在尚无适用的本地工具清单时执行
dotnet new tool-manifest

dotnet tool install dotnet-aspnet-codegenerator --version 8.0.7
dotnet add .\BookWeb.csproj package Microsoft.VisualStudio.Web.CodeGeneration.Design --version 8.0.7

dotnet build .\BookWeb.csproj
dotnet aspnet-codegenerator area Admin --project .\BookWeb.csproj

如果清单中已经安装了该工具,可使用 dotnet tool update 指定版本。

如果命令行成功、Visual Studio 失败,可以将排查范围缩小到 IDE 集成、组件版本或环境差异等方向。如果两者都失败,则继续查看各自的具体错误。两条执行路径并不完全相同,仅凭其中一条成功,还不能确定根因。

只需要创建 Area 时,可以手动完成

MVC Area 可以通过目录、控制器特性和路由配置建立,无需使用 scaffolding,也不需要为此增加 EF Core 包。Area 配置说明

例如,创建以下文件:

Areas/
└── Admin/
    ├── Controllers/
    │   └── HomeController.cs
    └── Views/
        └── Home/
            └── Index.cshtml

Areas/Admin/Controllers/HomeController.cs:

using Microsoft.AspNetCore.Mvc;

namespace BookWeb.Areas.Admin.Controllers;

[Area("Admin")]
public class HomeController : Controller
{
    public IActionResult Index()
    {
        return View();
    }
}

Areas/Admin/Views/Home/Index.cshtml:

@{
    Layout = null;
}

<h1>Admin</h1>

在现有 Program.cs 中,将 Area 路由放在普通默认路由之前:

app.MapControllerRoute(
    name: "areas",
    pattern: "{area:exists}/{controller=Home}/{action=Index}/{id?}");

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

项目应保留 MVC 服务注册:

builder.Services.AddControllersWithViews();

运行后,使用应用实际监听的地址访问 /Admin/Home/Index。这可以验证 Area 配置,但 scaffolding 的包还原问题仍需单独排查。

后续使用共享布局或 Tag Helpers 时,还要检查 Area 视图适用的 _ViewStart.cshtml、_ViewImports.cshtml。项目根目录下 Views 文件夹中的这些文件,不会自动作用于 Areas 中的视图。

备注:内容仅供参考。