Visual Studio 17.14.17更新后.NET 8 MAUI项目无法构建部署求助

问题背景 #

维护的.NET 8 MAUI应用在更新Visual Studio至17.14.17版本前，可正常构建并部署到Android和iOS平台；更新后项目完全失效，出现一系列异常。

具体错误症状 #

• 编辑器中所有文件标红，无法识别Microsoft.Maui.Controls、Android.App、UIKit等命名空间
• 随机构建错误：

Using directives must be placed outside of a namespace declaration
The type or namespace name 'MauiApp' could not be found
Assets file doesn't have a target for net8.0-android
SupportedOSPlatformVersion 13.1 cannot be higher than TargetPlatformVersion 1.0

• CLI构建报错：

Runtime list file 'Microsoft.NETCore.App.Runtime.Mono.android-x64\data\RuntimeList.xml' was not found.

• Android构建失败提示：

resource xml/maui_file_paths not found

• iOS运行时崩溃提示：

PlatformSetColor is only supported on iOS and Android 23 and later

环境信息 #

• 已安装SDK版本：

5.0.402
6.0.404
8.0.415
9.0.306

• 项目目标框架：

<TargetFrameworks>net8.0-android;net8.0-ios;net8.0-maccatalyst</TargetFrameworks>

• 当前已安装工作负载：

dotnet workload list

Installed Workload Id      Manifest Version       Installation Source
-------------------------------------------------------------------------------
aspire                     8.2.2/8.0.100          SDK 8.0.400, VS 17.14.36603.0
android                    34.0.79/8.0.100        VS 17.14.36603.0
maui-windows               8.0.61/8.0.100         VS 17.14.36603.0
maccatalyst                17.2.8022/8.0.100      VS 17.14.36603.0
ios                        17.2.8022/8.0.100      VS 17.14.36603.0

已尝试的无效操作 #

• 重新安装并修复所有.NET 8 MAUI工作负载
• 通过global.json固定SDK版本为8.0.415：

{ "sdk": { "version": "8.0.415" } }

• 修复工作负载并重建MAUI 8环境，编辑器仍无法识别项目引用，平台特定代码报错

疑问与需求 #

1. 为何常规Visual Studio更新会导致稳定的.NET 8 MAUI项目失效？
2. 如何修复或回滚解决问题？

一、问题根源 #

Visual Studio 17.14.17更新时，可能自动升级了MAUI相关工作负载的依赖版本，导致与.NET 8 SDK 8.0.415不兼容；同时更新过程中可能出现文件损坏、工作负载注册异常，或者多版本SDK/工作负载混合引发的环境混乱。

二、修复步骤 #

1. 彻底清理环境残留 #

• 以管理员权限打开命令提示符，卸载所有MAUI相关工作负载：

dotnet workload uninstall android ios maccatalyst maui-windows

• 在控制面板→程序和功能中卸载.NET SDK 8.0.415
• 删除以下目录的残留文件：
  • C:\Program Files\dotnet\sdk-manifests\8.0.100中与MAUI、Android、iOS相关的文件夹
  • C:\Program Files\dotnet\packs下所有Microsoft.Maui.*、Microsoft.Android.*、Microsoft.iOS.*开头的包目录
  • 项目目录下的bin、obj文件夹，以及.vs隐藏目录

2. 重新安装匹配版本的SDK与工作负载 #

• 安装.NET 8 SDK 8.0.415
• 执行命令安装对应版本的MAUI工作负载：

dotnet workload install android ios maccatalyst maui-windows --sdk-version 8.0.415

• 验证安装结果，确保工作负载的安装来源为SDK 8.0.415：

dotnet workload list

3. 修复项目配置 #

• 打开项目.csproj文件，添加明确的平台版本配置，避免版本冲突：

<!-- Android配置 -->
<AndroidTargetSdkVersion>34</AndroidTargetSdkVersion>
<AndroidMinSdkVersion>21</AndroidMinSdkVersion>
<SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'android'">21</SupportedOSPlatformVersion>

<!-- iOS配置 -->
<SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'ios'">13.1</SupportedOSPlatformVersion>
<IOSSdkVersion>17.2</IOSSdkVersion>

• 清理并重建项目：

dotnet clean
dotnet restore
dotnet build

4. 回滚Visual Studio（若修复无效） #

• 打开Visual Studio Installer，点击「更多」→「卸载」，选择回滚到更新前的版本（如17.14.16）
• 回滚完成后重新验证项目构建与运行

三、预防措施 #

• 完善global.json配置，严格禁用SDK自动升级：

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

• 关闭Visual Studio自动更新，或更新前备份项目与开发环境

内容的提问来源于stack exchange，提问作者Teoman shipahi