90%的MAUI项目启动失败源于环境配置错误，而非代码问题：需确保安装正确版本的.NET SDK（如8.0.400）、接受Android SDK许可、启用Hyper-V或WSL2、选用带Google APIs的Android模拟器镜像并设Graphics为Hardware-GLES 2.0，且ANDROID_HOME路径不含中文、空格或括号。
MAUI 项目跑不起来，90% 的问题出在环境没配对，不是代码写错了。直接上手就编译失败、模拟器黑屏、Android 启动闪退——这些都不是“运气差”，而是 SDK、工作负载、许可、虚拟化四者中至少有一项没到位。
dotnet --list-sdks 显示不出 6.0+ 条目？先装对 SDK
VS 装得再新也没用，dotnet 命令行才是 MAUI 构建的真实入口。如果 dotnet --list-sdks 输出里没有 6.0.x、7.0.x 或 8.0.x（推荐用 8.0.400 稳定版），说明 .NET SDK 根本没装进系统路径。
- 去 dotnet.microsoft.com/download/dotnet/8.0 下完整离线安装包（别用 Visual Studio 自带的“精简版”SDK）
- 安装后重启终端，再运行
dotnet --list-sdks确认输出含8.0.400类似条目 - 别碰 .NET 9 预览版——截至 2026 年 4 月，MAUI 模板尚未完全适配，
dotnet new maui会报Could not find template
VS 安装器里勾了“.NET MAUI 工作负载”，但新建项目仍报错？检查 Android SDK 许可和 Hyper-V
工作负载只是“模板+工具链”，真正构建 Android APK 还要靠 Android SDK 和 Windows 虚拟化支持。错误信息里只要出现 license、Android SDK Platform、Hyper-V 字样，基本就是这三件事没做完。
- 在 VS 中打开“错误列表”，双击任何带
license的报错，逐个点 Accept（通常有 3–5 个，包括platforms;android-34、build-tools;34.0.0、emulator） - 以管理员身份运行 PowerShell，执行：
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All -NoRestart，然后重启电脑 - Windows 11 家庭版用户注意：Hyper-V 不可用，必须改用 WSL2 + Android Emulator，否则模拟器根本不会启动
Android 模拟器启动卡在 “Creating device…” 或白屏？Graphics 设置和镜像类型是关键
VS 默认创建的模拟器依赖 x86_64 镜像 + GLES 2.0 硬件加速。选错镜像或关了加速，就会 CPU 占满、黑屏、日志里反复刷 libmonosgen-2.0.so not found。
- 打开 VS → 工具 → Android → Android Device Manager → 新建设备时，只选带
Google APIs的镜像（如Pixel 5 API 34），别选Android TV或Wear OS - 设备创建完成后，右键 → Edit → Show Advanced Settings → Graphics 必须设为
Hardware - GLES 2.0（Software 模式会导致 MAUI 启动失败） - 首次启动可能耗时 5 分钟以上，看到状态栏变成
Running且底部出现Stop按钮才算成功
Platforms/Windows/App.xaml.cs 里找不到 OnLaunched？平台专用代码不能乱放
MAUI 的生命周期入口是按平台隔离的，不是所有逻辑都堆在 App.xaml.cs 里。硬往主项目加 OnLaunched 或调用 Platform.Init()，编译直接报错或运行时重复初始化。
-
OnLaunched只存在于Platforms/Windows/App.xaml.cs，不是App.xaml.cs - Android 初始化（如
Microsoft.Maui.Essentials.Platform.Init()）已由框架自动完成，手动调用会触发InvalidOperationException: Platform already initialized - 需要设置高 DPI 支持？只在
Platforms/Windows/App.xaml.cs的OnLaunched方法里加app.SetHighResolution(true)，别写错位置
最常被忽略的其实是 Android SDK 路径——ANDROID_HOME 环境变量指向的目录名里不能有中文、空格或括号，哪怕只是“Program Files (x86)”也会让 MAUI 在打包资源阶段静默失败，最终 APK 缺 Resources/Drawable 导致闪退。这点连 VS 错误窗口都不会提示，只能看 dotnet build -t:Run -f net8.0-android -v:d 的详细日志里找 Copying resource 是否中断。
