PAYATHON 2026

.NET MAUI 在 VS 2026 中还原失败并报 NU1102，如何解决？

数据小陈

优先检查 Windows 目标为何请求了 Microsoft.NETCore.App.Runtime.Mono.win-x64，并确认它使用 CoreCLR。单靠重新安装 CommunityToolkit.Maui 或反复执行 dotnet restore，无法解决这个错误。

.NET 9 已停止提供这类桌面 MonoVM 运行时包，因此不应继续寻找该包的 9.0.14 正式版本，也不应改用错误提示中的预览版。微软的兼容性说明列出了这一变化。

目前还不能确定是哪个项目属性、导入文件或工具链差异触发了 Mono 运行时选择。CommunityToolkit.Maui 无法重新安装的问题，也需要结合它自己的错误日志判断。

1. 先检查 Windows 目标框架和运行时属性

.NET MAUI 的 Windows 目标使用 CoreCLR，移动平台的运行时选择则不同。可参考微软的运行时说明。

检查以下位置是否设置了 UseMonoRuntime，或者存在没有平台条件的运行时配置：

  • 项目的 .csproj。
  • 项目及上级目录中的 Directory.Build.props、Directory.Build.targets。
  • 发布配置 .pubxml。
  • 自定义导入的 .props、.targets 和构建命令参数。

可以在 .csproj 中为 Windows 目标显式设置：

<PropertyGroup Condition="'$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)'))' == 'windows'">
  <UseMonoRuntime>false</UseMonoRuntime>
</PropertyGroup>

这项设置应限定在 Windows 目标，避免影响 Android、iOS 或 Mac Catalyst 的运行时选择。如果后续导入的文件再次覆盖了它，还需要修改覆盖来源。

同时，检查此前加入的配置：

<TargetFramework>net9.0</TargetFramework>
<RuntimeIdentifier>win-x64</RuntimeIdentifier>

net9.0 没有表达 MAUI 所需的平台目标；win-x64 只指定运行时标识符，不能补足 Windows 目标框架信息。应恢复项目原有的 MAUI TargetFrameworks 配置，并确认其中包含 Windows 目标。

例如，Windows TFM 可以是 net9.0-windows10.0.19041.0。这只是示例，实际应使用项目已有且受环境支持的 Windows TFM。不要直接覆盖整个跨平台目标列表，也不要把 win-x64 无条件应用到所有平台。

2. 确认实际使用的是哪个 SDK

安装了 SDK 9.0.312，并不代表当前命令或 IDE 一定选中了它。在解决方案目录执行：

dotnet --version
dotnet --info
dotnet --list-sdks
dotnet workload list

核对当前 SDK、SDK 安装路径和 workload 信息，并与 Visual Studio 的生成输出比较。Developer PowerShell 中的 dotnet 结果可以作为线索，但不能直接证明 IDE 内部使用了完全相同的构建环境。

目标框架与构建 SDK 是两个独立概念。不能仅因为项目目标是 .NET 9，就认定使用 .NET 10 SDK 一定有错。微软的 global.json 文档说明了 SDK 的选择规则。

如果需要将已安装的 9.0.312 作为排查基线，可以在解决方案目录创建或合并以下 global.json：

{
  "sdk": {
    "version": "9.0.312",
    "rollForward": "disable"
  }
}

这里的 disable 要求精确匹配该 SDK。如果已有 global.json，应保留其中其他有效设置，并确认当前 Visual Studio 支持所选 SDK。该文件不会安装 SDK，也不会自动补齐 workload。

3. 检查 workload，再重新还原

确认 SDK 选择后，在解决方案目录检查项目需要的 workload：

dotnet workload restore

该命令用于分析项目并安装缺失的 workload，具体行为见 dotnet workload restore 文档。如果提示 Visual Studio 管理的组件需要通过安装器维护，再到 Visual Studio Installer 中检查对应实例的 .NET MAUI 工作负载。

修正项目配置后，关闭 Visual Studio，删除受影响项目的 bin、obj 生成目录，然后重新打开并执行：

dotnet restore --force --verbosity diagnostic > restore.log 2>&1

在日志中查找 Microsoft.NETCore.App.Runtime.Mono.win-x64、UseMonoRuntime、RuntimeIdentifier 和 9.0.14，确认修正后是否仍在请求 Windows Mono 运行时包。

如果仍然出现同一请求，应继续定位属性覆盖和运行时包解析过程。重复清理不会改变错误的运行时选择。

4. 单独检查 NuGet 包源与映射

NU1102 表示已找到包 ID，但参与解析的源中没有满足版本要求的版本。它本身不能证明网络下载失败。错误中的 Versions ... were not considered 还提示需要检查包源映射，参见 NU1102 说明。

先列出当前启用的源：

dotnet nuget list source

然后检查项目、解决方案、上级目录和用户级的 NuGet.Config，重点关注：

  • nuget.org 是否启用，地址是否正确。
  • 是否有 <clear /> 改变了继承的源列表。
  • 是否设置了 <packageSourceMapping>。
  • 映射是否覆盖 CommunityToolkit.Maui 及其传递依赖。

启用 Package Source Mapping 后，直接依赖和传递依赖都必须匹配可用源的规则，详见包源映射文档。不要为了试错直接删除项目已有的私有源或映射。

C:\Program Files\dotnet\library-packs 未被考虑，不代表该目录损坏，也不能说明目标版本就在其中。对于已经停止提供的 Windows Mono 正式版运行时包，调整映射无法解决错误的包请求。

5. 根据后续错误判断依赖是否需要调整

当前依赖列表同时包含 9.x 和 10.x 包，但包的主版本号不同不能直接作为不兼容的证据。应根据各包支持的目标框架、依赖约束和后续还原错误逐项判断。

同一项目在 VS 2022 中正常、新项目可以添加相同包，说明应重点比较旧项目的构建属性、导入文件、SDK、workload 和 NuGet 配置。这些现象还不足以确定唯一原因。

修复后，首先确认 Windows 目标不再请求 Microsoft.NETCore.App.Runtime.Mono.win-x64 9.0.14。如果 CommunityToolkit.Maui 仍然失败，再查看它对应的完整错误码、包源和失败依赖，继续处理剩余问题。

备注：内容仅供参考。