MAUI项目必须使用.NET 6+ SDK并安装对应工作负载，Android需配置英文路径与GLES 2.0渲染，Windows需启用高分辨率支持，iOS真机调试须绑定付费开发者账号及Xcode自动签名。
MAUI项目必须用.NET 6+ SDK，旧版VS直接报错
你装了最新Visual Studio但新建MAUI项目失败，大概率是SDK版本不匹配。MAUI从诞生起就绑定.NET 6，.NET 5及更早版本根本不识别Microsoft.Maui工作负载。
实操建议：
- 运行
dotnet --list-sdks，确认输出里有类似6.0.400或7.0.400的条目；没有就去dotnet.microsoft.com/download下.NET 6或7 SDK（别下.NET 8预览版，部分MAUI模板还不稳定） - VS安装器里必须勾选「.NET MAUI跨平台应用开发」工作负载——光装SDK不够，还得有模板和工具链
- 如果用命令行创建项目，必须用
dotnet new maui，而不是dotnet new console后手动改csproj，后者会漏掉关键UseMaui=true属性和资源引用
Android模拟器启动黑屏或卡在“Starting…”
这是MAUI新手最常卡住的点：项目能编译，但dotnet build -t:Run -f net7.0-android后模拟器只显示白屏或根本没反应。问题通常不在代码，而在环境配置。
实操建议：
- 检查Android SDK路径是否含中文或空格——
ANDROID_HOME环境变量指向的路径必须是纯英文、无空格，否则MAUI构建时会静默失败 - 模拟器必须启用
Hardware - GLES 2.0渲染（AVD Manager → Edit → Show Advanced Settings → Graphics），选Software - GLES 2.0会导致启动极慢甚至黑屏 - 首次运行前务必先执行
dotnet workload install maui，否则dotnet build可能跳过Android资源打包步骤，导致APK里缺Resources/Drawable目录，App一启动就闪退，错误日志里会出现System.IO.FileNotFoundException: Could not find file 'libmonosgen-2.0.so'
Windows桌面端跑起来但UI缩放异常（文字糊、按钮错位）
MAUI默认按96 DPI渲染，但Win10/11用户大量使用125%、150%系统缩放。不处理的话，Label文字发虚，Button尺寸错乱，甚至整个页面被裁剪。
实操建议：
- 在
Platforms/Windows/App.xaml.cs的OnLaunched方法里加这行：app.SetHighResolution(true)（注意不是EnableHighResolution，那个是旧API） - 所有硬编码宽高（比如
WidthRequest="200"）立刻换成相对单位：Grid列定义用*或Auto，控件用HorizontalOptions="FillAndExpand" - 避免在XAML里写
FontSize="16"，改用FontSize="{DynamicResource BodyFontSize}"，并在Resources/Styles.xaml里定义响应式字号映射
iOS真机调试连不上，Xcode报错「No signing certificate "iOS Development" found」
MAUI不支持纯模拟器开发iOS，必须连真机且完成证书配置。Xcode报这个错，说明本地钥匙串里没对应开发证书，或Apple ID没加入开发者计划。
实操建议：
- 打开Xcode → Preferences → Accounts，添加你的Apple ID，并确保状态显示「Member」（个人免费账号不行，必须是$99/年付费开发者账号）
- 在Xcode里新建一个空iOS项目，让它自动帮你生成开发证书和Provisioning Profile——MAUI会复用这套配置，别试图手动导出P12再导入，容易权限错乱
- 连接iPhone后，在VS里选中
net7.0-ios目标，右键项目 → Properties → iOS Bundle Signing → 把Signing Identity设为iPhone Developer，Provisioning Profile选Automatic，别手选具体Profile
MAUI的跨平台不是“写一次到处跑”，而是“同一套逻辑+三套平台适配”。最容易被忽略的是：Android要管DPI和权限声明，Windows要调DPI适配和窗口生命周期，iOS必须走Xcode证书流——漏掉任一环，都是黑屏、闪退或UI错位，不是代码问题。
