前言：为什么选择 .NET MAUI？
在跨平台开发领域，虽然 Flutter、React Native 和 Electron 等框架已非常流行，但微软推出的 .NET MAUI（.NET Multi-platform App UI），作为 Xamarin.Forms 的正式继任者，凭借“一套代码、多端运行”的能力，正成为 .NET 生态中构建现代化应用的重要选择。
它具备原生性能，直接调用各平台原生控件而非 WebView；使用统一的 C# 和 XAML 语言，无需额外学习 Dart 或 JavaScript/TypeScript；并能与 ASP.NET Core、Entity Framework 和 Azure 等服务深度集成。作为一个开源且免费的项目，它在 GitHub 上保持着活跃的维护。
然而，许多开发者反映官方文档较为碎片化，概念跳跃且缺乏实战引导。本文旨在弥补这一空白，以构建一个真实应用为主线，系统性地讲解 .NET MAUI 的核心知识体系，帮助你从能运行代码到精通框架。
第一章：环境搭建与项目结构全景
1.1 开发环境准备
在 Windows 上进行开发，需要准备以下组件：
- Visual Studio 2022（17.3 或更高版本）：安装时务必勾选 “.NET Multi-platform App UI development” 工作负载。
- .NET SDK 8.0（推荐使用）。
- Android SDK 和模拟器，用于 Android 应用的调试。
- 可选：一台用于配对的 Mac 电脑，以便进行 iOS 应用的编译。
安装完成后，可以通过命令行进行验证：
dotnet --list-sdks // 应包含 8.0.x 版本
dotnet workload list // 应包含 maui 工作负载
如果尚未安装 MAUI 工作负载，可以通过以下命令安装：
dotnet workload install maui
1.2 创建第一个项目
你可以通过命令行快速创建一个新项目：
dotnet new maui -n MyMauiApp
cd MyMauiApp
dotnet build
当然，也可以通过 Visual Studio 2022 的“创建新项目”窗口，直接搜索并创建“.NET MAUI App”。
1.3 项目结构详解
一个典型的 .NET MAUI 项目结构如下：
MyMauiApp/
├── App.xaml / App.xaml.cs // 应用入口点
├── AppShell.xaml / AppShell.xaml.cs // Shell 导航容器（默认启用）
├── MainPage.xaml // 主页面
├── Platforms/ // 各平台专属代码
│ ├── Android/ // 包含 AndroidManifest.xml, MainActivity
│ ├── iOS/ // 包含 Info.plist, AppDelegate
│ ├── MacCatalyst/
│ └── Windows/ // 包含 Package.appxmanifest
├── Resources/ // 资源文件目录
│ ├── Styles/ // 全局样式文件，如 Colors.xaml, Styles.xaml
│ ├── Images/ // 图片资源，支持自动适配不同 DPI
│ └── Raw/ // 原始文件，如 JSON 配置文件或 SQLite 数据库
├── MauiProgram.cs // 应用启动配置（依赖注入、服务注册）
└── MyMauiApp.csproj // 项目文件，其中定义了目标框架
设计的核心思想是：将共享的业务逻辑和 UI 代码写在项目根目录，而对于不同平台间的差异，则通过在 Platforms/ 目录下创建分部类（partial class）来实现。
第二章：XAML 与 UI 构建体系
2.1 XAML 基础
XAML（eXtensible Application Markup Language）是一种基于 XML 的声明式语言，用于定义用户界面结构。在编译时，XAML 会被转换为相应的 C# 代码，并通过页面的 InitializeComponent() 方法加载。
例如，以下 XAML 代码：
<Label Text="Hello MAUI!" FontSize="24" />
在功能上等价于以下 C# 代码：
var label = new Label { Text = "Hello MAUI!", FontSize = 24 };
使用 XAML 的优势在于结构清晰、易于设计工具支持，并能很好地实现 UI 与后台逻辑的分离。
2.2 核心控件速览
.NET MAUI 提供了一系列基础控件用于构建界面：
Label：用于文本显示，常用属性有Text,FontSize,TextColor。Button：按钮，常用属性有Text,Clicked事件,BackgroundColor。Entry：单行文本输入框，常用属性有Text,Placeholder,Keyboard。Editor：多行文本输入框。Image：用于显示图片。CheckBox：复选框。Switch：开关控件。DatePicker/TimePicker：日期和时间选择器。
所有控件都继承自 View 基类，因此都支持 HorizontalOptions、VerticalOptions、Margin、Padding 等通用的布局属性。
2.3 布局容器（Layouts）
布局容器是构建 UI 的骨架，MAUI 提供了多种选择：
1. VerticalStackLayout / HorizontalStackLayout
这两种布局以线性方式排列其子元素，分别垂直排列和水平排列。它们适用于构建简单的表单、按钮组或列表项。
2. Grid
网格布局是功能最强大的容器之一，它通过定义行和列来组织子元素，并支持子元素跨行或跨列。适用于构建复杂的界面，如登录页面或仪表盘。
3. FlexLayout
弹性布局，其行为类似于 CSS 中的 Flexbox，能够创建响应式的流式布局。
4. ScrollView
当内容可能超出屏幕显示范围时，应将其包裹在 ScrollView 中以实现滚动。需要注意避免嵌套 ScrollView，否则可能引发性能问题。
最佳实践建议：优先组合使用 Grid 和 StackLayout 来构建界面；避免布局嵌套超过三层；多使用 Spacing 和 Padding 属性来调整间距，而非硬编码 Margin 值。
第三章：导航系统深度解析（Shell vs 传统）
导航是 .NET MAUI 应用中的重要概念。值得注意的是，Xamarin.Forms 中的 NavigationPage 在 MAUI 中已被移除，取而代之的是全新的 Shell 导航模型。
3.1 Shell：现代导航的首选
Shell 提供了一个声明式的导航容器，支持基于 URI 的页面路由、底部标签栏、侧边栏菜单，并自动管理页面的返回栈。
基础结构定义通常在 AppShell.xaml 文件中。你可以定义单页面模式，也可以定义包含多个标签页的复杂导航结构。页面间的跳转通过 Shell.Current.GoToAsync() 方法实现，你还可以在 URI 中附带查询参数。在目标页面中，可以使用 [QueryProperty] 特性来接收这些参数。
一个常见的问题是避免重复打开同一个页面。推荐的解决方案是检查当前的路由状态，如果即将跳转的页面已经是当前页面，则取消跳转。另一种方法是使用以 // 开头的绝对路由，这会在跳转前清空导航栈，从而确保目标页面的唯一性。通常不推荐尝试复用同一个页面实例，因为这会增加生命周期管理的复杂度。
3.2 传统导航（仅作了解）
如果你没有使用 Shell，理论上仍然可以通过 Navigation.PushAsync() 进行页面导航。但是，.NET MAUI 已不再内置 NavigationPage 这个导航容器，因此这种方式受到很大限制，通常不推荐在新项目中使用。
结论是明确的：对于新项目，应始终坚持使用 Shell 进行导航。
第四章：样式、主题与资源管理
4.1 全局样式
你可以在 Resources/Styles/ 目录下的 XAML 文件（如 Styles.xaml）中定义全局样式和资源。这里可以定义颜色、样式等，并通过 StaticResource 或 DynamicResource 在应用内引用。一个非常有用的标记是 AppThemeBinding，它可以根据系统当前是亮色还是暗色主题自动切换资源值，从而实现深色模式适配。
4.2 主题切换
你可以在代码中强制设置应用的主题，也可以监听系统主题的变化事件，以便在主题切换时更新你的界面。
4.3 资源管理
- 图片资源：应放入
Resources/Images/目录，并将其生成操作设置为MauiImage。框架会自动处理不同分辨率的适配问题。 - 字体与图标：自定义字体文件放入
Resources/Fonts/目录，生成操作设置为MauiFont，即可在 XAML 或代码中使用。
第五章：数据绑定与 MVVM 模式
5.1 数据绑定简介
数据绑定实现了 UI 控件与后台数据源之间的自动同步，当数据发生变化时，UI 会自动更新，无需手动操作控件。
5.2 实现 INotifyPropertyChanged
要使数据绑定生效，数据源（通常是 ViewModel）需要实现 INotifyPropertyChanged 接口。当属性的值发生变化时，需要触发 PropertyChanged 事件来通知 UI 更新。
5.3 绑定上下文
在页面（View）中，需要设置 BindingContext 属性为对应的 ViewModel 实例，从而建立视图与视图模型之间的关联。
5.4 使用 CommunityToolkit.MVVM 简化
为了减少样板代码，强烈推荐使用 CommunityToolkit.MVVM 库。它通过源代码生成器，让你只需使用 [ObservableProperty] 标记字段，即可自动生成实现了通知的完整属性；使用 [RelayCommand] 标记方法，即可自动生成命令。这极大地简化了 ViewModel 的编写。
第六章：列表与集合展示
6.1 使用 CollectionView
ListView 控件在 MAUI 中已被视为过时，CollectionView 是当前推荐用于展示列表数据的控件，它在性能和功能上都有显著提升。
6.2 基础用法与高级功能
通过设置 ItemsSource 属性绑定数据集合，并在 ItemTemplate 中定义每一项的呈现模板。CollectionView 原生支持分组显示、项目选择、上拉加载更多等常见功能。
6.3 性能优化
CollectionView 默认启用了虚拟化和元素回收策略以确保滚动流畅。为了保持高性能，应避免在数据项模板中嵌套过于复杂的布局结构。
第七章：平台特定功能
7.1 实现方式
当需要调用振动、生物识别、特定平台通知等原生功能时，有以下两种主要实现方式：
1. 使用分部类：在共享项目中定义接口和部分方法声明，然后在各平台的特定项目中实现具体逻辑。
2. 依赖注入（推荐）：在共享项目中定义功能接口，在各平台项目中提供具体实现。然后在 MauiProgram.cs 启动文件中，将平台特定的实现注册到依赖注入容器中。在共享代码中，通过服务定位器或构造函数注入来获取接口实例并使用。这种方式解耦性好，便于单元测试。
第八章：生命周期与事件处理
8.1 页面生命周期
页面具有关键的生命周期方法：
OnAppearing()：在页面即将显示时调用，适合在此处加载数据或启动一些任务。OnDisappearing()：在页面即将隐藏时调用，适合保存状态或停止任务。
需要注意的是，应避免在页面构造函数中进行耗时操作（如网络请求），这些操作更适合放在OnAppearing中。
8.2 应用生命周期
在 App.xaml.cs 中，可以重写 OnStart、OnSleep、OnResume 等方法，以响应应用的启动、进入后台和从后台恢复等事件。可用于管理全局状态，如保存草稿、更新令牌等。
8.3 事件与命令
对于按钮点击等交互，可以使用直接的事件处理器，这种方式简单直接，适合处理局部逻辑。在 MVVM 模式下，则推荐使用绑定命令（Command），将用户交互与 ViewModel 中的方法关联起来，更好地实现关注点分离。
第九章：网络请求与本地存储
9.1 网络请求
直接使用 .NET 内置的 HttpClient 类即可进行 HTTP 通信。建议将网络请求封装成独立的服务类，并注册为单例或作用域服务，以便通过依赖注入进行管理。
9.2 本地存储
- 轻量级存储：使用
Preferences类，它提供键值对形式的持久化存储，适合保存用户设置等简单数据。 - 结构化存储：对于复杂数据，可以使用 SQLite 数据库。通过
sqlite-net-pcl等库，可以方便地定义实体类并进行增删改查操作。
第十章：调试、测试与发布
10.1 调试
充分利用 Visual Studio 的 热重载 功能，可以在修改 XAML 或 C# 代码后立即看到效果，无需重新启动应用。配合输出窗口和真机调试，可以高效地定位问题。
10.2 测试
为 ViewModel 和业务服务编写单元测试是保证应用质量的重要手段。可以使用 xUnit 或 NUnit 等测试框架。对于 UI 交互的测试则相对复杂，可能需要专门的 UI 测试框架。
10.3 发布准备
发布前需要准备好各平台的应用图标和启动屏幕图片，并放置在指定的资源目录中。对于 Android 应用，需要在清单文件中声明所需的权限。在发布构建时，可以启用代码裁剪来减小最终应用包的体积，但需要注意，如果项目中使用了反射等动态特性，可能需要额外的配置来防止必要的代码被错误裁剪。
第十一章：性能优化与最佳实践
- 布局优化：保持布局扁平化，避免过度嵌套。合理选择布局容器，例如用
Grid替代多个嵌套的StackLayout。 - 内存管理：及时取消对事件或消息的订阅，防止内存泄漏。对于可能持有页面引用的回调，考虑使用弱引用。
- 启动速度：尽量减少
MauiProgram.cs中启动服务的初始化耗时，将非关键资源的初始化延迟进行。合理设计启动页以提升用户对速度的感知。
第十二章：常见问题与解决思路
- XAML 修改不生效：尝试清理解决方案并重新构建，或重启开发环境。
- 图片不显示：检查图片是否已放入
Resources/Images/目录，并且生成操作是否为MauiImage。 - 多次点击打开多个相同页面：在跳转逻辑中加入对当前路由状态的判断。
- Android 权限被拒绝：在 Android 6.0 及以上版本，部分危险权限需要在运行时动态向用户申请。
结语
.NET MAUI 作为一个仍在快速发展的框架，已经具备了用于生产环境的能力。随着 .NET 版本的持续更新，其工具链、性能和社区生态将会越来越完善。
学习路径建议：
- 从掌握 Shell 导航和 XAML 基础布局开始。
- 深入实践 MVVM 模式和数据绑定。
- 学习集成网络请求和本地数据持久化。
- 尝试调用一些平台特定的原生功能。
- 最终尝试将一个完整的应用发布到应用商店。
记住，跨平台开发的核心目标不是追求“一份代码处处运行”，而是实现“一套核心业务逻辑，为不同平台提供各自最佳的用户体验”。尊重并适配不同平台的交互规范，才是专业的做法。
附录：推荐资源
- 官方文档：Microsoft Learn 上的 .NET MAUI 文档是首要的学习资源。
- 示例代码：GitHub 上的官方示例仓库包含了大量实际场景的代码。
- 社区：.NET 基金会论坛下的 MAUI 板块是交流和解决问题的好地方。