MAUI项目升级.NET版本教程

MAUI项目升级.NET版本需同步更新目标框架、SDK声明和开发环境支持；检查VS与SDK兼容性，修改.csproj中TargetFramework为net8.0-*，重装maui工作负载，更新NuGet包并清理bin/obj。

MAUI 项目升级 .NET 版本，核心是同步更新 目标框架（Target Framework）、SDK 版本声明 和 开发环境支持。不是只改一个地方就能跑起来，漏掉任一环节都可能编译失败或运行异常。

确认当前环境与目标版本兼容性

MAUI 对 .NET SDK 版本有明确要求：.NET 7 是最低支持版本，.NET 8 是当前主流稳定版，.NET 9（预览中）部分功能已可试用。升级前先检查：

• Visual Studio 版本是否匹配（如 .NET 8 需 VS 2022 17.8+）
• 全局安装的 .NET SDK 是否已下载目标版本（运行 dotnet --list-sdks 查看）
• 项目中 global.json 是否锁定了旧 SDK（如有，需更新 version 字段）

修改项目文件（.csproj）中的 TargetFramework

这是最关键的一步。打开你的 MAUI 主项目（通常是 YourApp.csproj），找到 <TargetFramework> 节点：

• 从 net7.0-android / net7.0-ios 升级到 net8.0-android / net8.0-ios
• 若支持多平台，保持多目标格式，例如：
  <TargetFrameworks>net8.0-android;net8.0-ios;net8.0-maccatalyst;net8.0-windows10.0.19041.0</TargetFrameworks>
• 注意：.NET 8 开始，Windows 默认使用 windows10.0.19041.0（而非旧版 win10-x64）

更新 MAUI 工作负载和 NuGet 包

.NET SDK 升级后，MAUI 工作负载不会自动更新，必须手动修复：

• 在终端运行：dotnet workload install maui（会自动匹配当前 SDK 版本）
• 如果提示已安装但版本不匹配，先卸载再重装：dotnet workload uninstall maui && dotnet workload install maui
• 检查项目中 MAUI 相关 NuGet 包（如 Microsoft.Maui.Controls）是否为对应版本（.NET 8 对应 8.x.x，不要混用 7.x）
• 建议删除 obj/ 和 bin/ 文件夹，再重建项目

处理常见编译/运行问题

升级后首次构建容易遇到以下典型问题：

• “The SDK 'Microsoft.NET.Sdk.Maui' specified could not be found” → 检查 workload 是否安装成功，或重启 VS
• Android 构建报错 AOT 或 linker 相关问题 → 在 .csproj 中临时添加：
  <PropertyGroup><TrimMode>copy</TrimMode></PropertyGroup>（.NET 8 默认启用 trim，部分第三方库不兼容）
• iOS 模拟器启动黑屏或卡住 → 确保 Xcode 命令行工具路径正确（xcode-select --install），并清理模拟器缓存
• 资源图标/启动图未更新 → 清理平台特定缓存（如 Android 的 Resources\drawable-* 重命名触发重建）

基本上就这些。升级本身不复杂，但容易忽略 workload 同步和缓存清理。改完 TargetFramework 后，务必重新安装 workload 并清空中间文件，再构建一次——多数问题就解决了。