.NET MAUI 就是微软推出的、用 C# 和 XAML 写一套代码就能跑在 Android、iOS、Windows、macOS 四个平台上的原生跨平台 UI 框架——它不是“模拟器”或“WebView 壳”，而是把你的
Button、
Label、
ListView等控件，实时翻译成各平台真正的原生控件（比如 iOS 的
UIButton、Windows 的
WinUI Button），所以性能和体验接近原生。
它不是 Xamarin.Forms 的“升级补丁”，而是重写：控件层全换、渲染路径更短、项目结构彻底扁平化（单项目，不再有 .iOS/.Android 多项目嵌套）。
怎么快速验证自己环境能跑起来
别急着建项目，先确认基础链路通不通：
dotnet --version # 必须 ≥ 8.0（推荐 9.0，2025 年底已稳定） dotnet workload list | findstr maui # 应看到类似：maui, maui-android, maui-ios, maui-windows... dotnet new maui -n TestApp && cd TestApp && dotnet build
如果
dotnet build报错说缺 workload，就立刻补：
dotnet workload install maui
常见坑：
Visual Studio 2022 17.8+安装时没勾选「.NET Multi-platform App UI 开发」——这会导致命令行能装 workload，但 VS 里新建项目模板不出现。必须重进 VS Installer → 修改 → 勾上它，再重启 VS。
创建第一个可运行的页面，关键三处不能漏
新建项目后，真正让 App 启动并显示内容，靠的是这三个文件协同：
App.xaml：定义全局资源字典（比如主题色、字体），它本身不决定“哪个页面先显示”
App.xaml.cs：里面
public partial class App : Application类，它的构造函数里有一句关键代码：
public App()
{
InitializeComponent();
MainPage = new AppShell(); // ← 这行决定了首屏！
}
MainPage.xaml（或
AppShell.xaml）：实际渲染的根页面。如果你删了
AppShell改用
MainPage，就得同步改
MainPage = new MainPage()
常见错误现象：
启动黑屏 / 白屏 → 检查MainPage = ...是否被注释或指向 null 编译通过但 Windows 上报错 “WinUI 3 runtime not found” → 需在 Windows 设置中开启「开发者模式」（设置 → 系统 → 针对开发人员 → 开启）
导航跳转为什么点不动？Navigation.PushAsync
失效的典型原因
Navigation.PushAsync(new DetailPage())不生效，90% 是因为当前页面根本不在导航栈里。
MAUI 要求：只有从
NavigationPage包裹的页面出发，才能用
Navigation属性跳转。
正确做法（两种）：
方式一（推荐）：在App.xaml.cs中这样设：
MainPage = new NavigationPage(new MainPage());方式二：用
AppShell（默认模板就是它），它内部自带导航容器，你只需确保跳转代码写在继承自
ContentPage的页面里，且调用时上下文是有效的页面实例（比如在按钮点击事件里）。
容易忽略的细节：
在App.OnStart()或静态方法里直接调用
Navigation.PushAsync→ 会抛
NullReferenceException，因为此时没有当前页面上下文 使用
Shell.Current.GoToAsync("//detail") 是另一套路由系统，和 Navigation不互通，混用会迷路
热重载（Hot Reload）为什么改了 XAML 没反应？
热重载不是万能的，它只对以下修改实时生效：
Text、
BackgroundColor、
FontSize等属性值变更 添加/删除简单控件（如加一个
Label）
但以下情况必须重新编译：
修改ViewModel的属性或绑定逻辑 更改页面继承关系（比如把
ContentPage改成
TabbedPage） 动态加载资源（如通过
ResourceManager切语言）
另外：Windows 上热重载默认只对 WinUI 生效；Android/iOS 模拟器需确保启用「Hot Reload on File Save」并在调试状态下运行（F5 启动，不是 Ctrl+F5）。
最常被卡住的一点：改完
MainPage.xaml后保存，但当前正在看的是
DetailPage——热重载只刷新当前激活页面，不会自动跳回去。
