必须先确认.net sdk≥6.0.300（推荐.net 8）且已安装maui、maui-android、maui-ios等工作负载，否则dotnet new maui会失败或项目无法编译运行；创建时可跳过不需要的平台以加速构建，并需按平台完成android jdk/sdk配置、windows开发者模式启用或macos xcode命令行工具初始化。
直接用 dotnet new maui 创建，但必须确认 SDK 版本和工作负载已就绪，否则项目生成后无法编译运行。
检查 .NET SDK 和 MAUI 工作负载是否安装到位
MAUI 不是装完 .NET SDK 就自动可用的——它依赖独立的工作负载（workload）。常见错误是执行 dotnet new maui 后提示“找不到模板”，或生成项目却在 VS / VS Code 中报错 The referenced project 'MauiApp1.csproj' does not exist，本质就是工作负载缺失。
- 运行
dotnet --list-sdks，确保有 ≥ .NET 6.0.300（推荐 .NET 8 SDK，MAUI 在 .NET 8 中正式稳定） - 运行
dotnet workload list，确认输出中包含maui、maui-android、maui-ios等条目 - 若缺失，执行
dotnet workload install maui（需联网，国内建议配好 NuGet 源或使用代理） - macOS 用户额外注意：iOS/iPadOS 工作负载仅在 macOS 上可用，且需 Xcode 14.2+ 和命令行工具
创建项目时选对模板和参数
dotnet new maui 是默认模板，但实际开发中常需跳过某些平台以加快首次构建——比如只做 Windows 或 Android 原型，没必要拉 iOS 的巨量依赖。
- 基础创建：
dotnet new maui -n MyFirstMauiApp - 跳过 iOS 构建（节省磁盘与时间）：
dotnet new maui -n MyFirstMauiApp --use-current-runtime false，再手动删掉.csproj中<targetframeworks>net8.0-android;net8.0-ios;...</targetframeworks>里不需要的部分 - 指定输出路径：
dotnet new maui -n MyFirstMauiApp -o ./src/maui - 不推荐用 visual studio 图形向导新建（尤其 VS 2022 17.4–17.7），容易生成带冗余 MSBuild 属性的项目，导致后续 CI 构建失败
首次运行前必须处理的三件事
哪怕模板生成成功，直接 dotnet run 也大概率失败。不是代码问题，而是环境链路没打通。
- Android：需提前安装 JDK 17（不是 JRE）、Android SDK Platform-Tools、至少一个 Android API 级别（如 android-34），并设置
ANDROID_HOME环境变量 - Windows：启用“开发者模式”（设置 → 系统 → 对于开发者），否则
dotnet run -t:Run -f net8.0-windows会卡在部署阶段 - macOS：首次运行
dotnet build -t:Run -f net8.0-maccatalyst前，先执行xcode-select --install并同意 Xcode 许可协议，否则报错xcrun: Error: invalid active developer path
真正卡住人的往往不是语法或 UI 写法，而是工作负载版本与 SDK 版本不匹配、Android 构建工具链权限未授、或 macOS 上 Xcode 命令行工具未初始化——这些不会在 C# 编译错误里体现，但会让 dotnet build 直接退出或挂起。