默认模板运行失败主因是SDK许可未签、Hyper-V未启用或net8.0-android框架缺失；需双击错误接受多个Android SDK许可，启用Hyper-V与Windows Hypervisor Platform并重启，确认VS已安装.NET MAUI工作负载及Android SDK组件。
直接上手就能跑，但默认模板会卡在 Android 构建或模拟器启动环节——核心问题不是代码写错，而是 SDK 许可没签、Hyper-V 没开、或 net8.0-android 目标框架没装全。
Visual Studio 创建 MAUI 项目后编译失败，错误里带 “license” 或 “Android SDK”
这是最常卡住新手的第一步。VS 新建 MAUI 项目时不会自动帮你接受 Android SDK 许可，也不会检查 Hyper-V 是否启用。错误信息通常长这样：The license for package Android SDK Platform 34 is not accepted.
- 双击“错误列表”里的这条报错，会自动弹出许可窗口；逐个点
Accept（注意：不止一个，可能有 3–5 个） - 打开“Windows 功能”，勾选
Hyper-V和Windows Hypervisor Platform，重启电脑 - 在 Visual Studio Installer 中确认已安装
.NET MAUI workload和Android SDK setup（不是只装了 .NET SDK 就够） - 如果用的是 Windows 11 家庭版，
Hyper-V不可用，得改用 WSL2 + Android Emulator，否则模拟器根本起不来
点击调试下拉菜单里的 “Android Emulator” 没反应，或卡在 “Creating device…”
这不是网络慢，而是 Android Device Manager 缺少系统镜像或硬件加速未生效。VS 默认创建的模拟器需要 x86_64 镜像 + Windows 虚拟化支持。
- 手动打开
Android Device Manager（VS 菜单：工具 → Android → Android Device Manager） - 点
Create Device→ 选Pixel 5或Pixel 4等带Google APIs的镜像（别选Android TV或Wear OS） - 镜像下载完成后，右键设备 →
Start；若弹出 “Enable Windows Hypervisor Platform”，必须点Run Anyway，否则模拟器 CPU 占用 100% 且黑屏 - 首次启动耗时可能超 5 分钟，期间不要关窗口；看到状态变成
Running且底部出现Stop按钮才算成功
App.xaml.cs 里 OnLaunched 方法不存在？别硬加
MAUI 项目结构和 UWP/Xamarin 不同，OnLaunched 是 Windows 平台专用生命周期方法，但它不在 App.xaml.cs 里，而在 Platforms/Windows/App.xaml.cs 中。直接在主 App 类里写会编译报错。
- 平台特定代码必须放在对应目录：
Platforms/Android/MainActivity.cs、Platforms/iOS/AppDelegate.cs、Platforms/Windows/App.xaml.cs - 比如想开启高 DPI 支持，得在
Platforms/Windows/App.xaml.cs的OnLaunched方法里加app.SetHighResolution(true)（不是EnableHighResolution，那是旧 API） - 主
App.xaml.cs只管跨平台生命周期事件：OnStart、OnResume、OnSleep，这些才是通用入口
运行起来界面模糊、文字小、按钮点不中？XAML 写法踩了硬编码坑
MAUI 不是“写一次，到处缩放”。所有像素级宽高、字号、边距都得换成响应式写法，否则在 iPad 或高分屏 Windows 上直接失真。
- 删掉所有
WidthRequest="200"、HeightRequest="44"，改用Grid列定义：<ColumnDefinition Width="*"/>或<ColumnDefinition Width="Auto"/> - 控件布局用
HorizontalOptions="FillAndExpand"替代固定尺寸 - 字号统一用动态资源：
FontSize="{DynamicResource BodyFontSize}"，并在Resources/Styles.xaml里按平台定义映射（例如 iOS 用 17，Android 用 16，Windows 用 14） - 别在 XAML 里写
Margin="10,5,10,5"，改用Style统一控制，否则不同屏幕密度下留白错乱
真正麻烦的从来不是“怎么写”，而是“哪些地方不能写”——MAUI 的跨平台抽象层会在你忽略平台差异的地方悄悄埋雷，比如字体渲染路径、触摸事件穿透、状态栏高度计算。这些细节不会报错，但会让应用在某个平台看起来“不太对”，而且很难复现。
