.NET MAUI是微软推出的原生跨平台UI框架，用C#和XAML一套代码编译为Android、iOS、Windows、macOS的原生控件；需dotnet 8.0+、安装maui workload，首屏由App.xaml.cs中MainPage=...指定，导航需NavigationPage或AppShell支持，热重载仅限部分XAML变更。
.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% 是因为当前页面根本不在导航栈里。
对于一个刚进入PHP 开发大门的程序员，最需要的就是一本实用的开发参考书，而不仅仅是各种快速入门的only hello wold。在开发的时候，也要注意到许多技巧和一些“潜规则”。PHP是一门很简单的脚本语言，但是用好它，也要下功夫的。同时，由于PHP 的特性，我一再强调，最NB 的PHP 程序员都不是搞PHP 的。为什么呢？因为PHP 作为一种胶水语言，用于粘合后端 数据库和前端页面，更多需
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 ——热重载只刷新当前激活页面，不会自动跳回去。
