简介《.NET MAUI实战指南》是一份面向.NET开发者的跨平台开发参考PDF内容围绕MAUI框架的核心原理与实战技巧展开涵盖基础控件、数据绑定、布局管理、MVVM架构、多平台适配与CI/CD部署全流程帮助开发者用单一共享代码库构建移动和桌面应用解决多端重复开发的痛点。资源为单个PDF文档包体约40.77MB来自Manning Publications出版的《.NET MAUI in Action》书中系统讲解了MAUI自下而上的分层设计、Handlers映射机制及各平台API的抽象方式编排清晰且权威性强。目前已有286人学习下载。读者可借助该书完整掌握MAUI从原理到落地的关键路径通过真实项目案例学习项目搭建、多平台适配和自动化部署有效提升跨平台应用的开发效率与交付质量。该书既适合刚接触MAUI的.NET工程师入门也适合有经验的开发者系统梳理知识体系、拓展多端开发技能。1. 为什么 .NET MAUI 值得现在动手从能用到好用的跨平台现实.NET MAUI 不是又一个跨平台 UI 框架的候选者而是 .NET 生态里唯一还在大规模迭代的一套代码跑 Android、iOS、macOS、Windows官方方案。早几年谈跨平台Xamarin.Forms 的控件渲染和启动性能确实让人犹豫但 MAUI 在架构上做了两件关键事把平台差异收敛到Platform文件夹的按平台实现里同时把绘制层从原生控件换成了可混用的 Handler 映射机制。这两点决定了 MAUI 的实际体验和 Xamarin.Forms 时代完全不同。很多人一上来被跨平台三个字带偏以为写一遍就跑四个端真正落地时才发现原生能力、权限、生命周期这些硬骨头一个都绕不开。这篇笔记不聊空洞的框架对比直接拆开讲怎么把 MAUI 用到能交付出的程度生命周期怎么接、依赖注入怎么组织、平台代码怎么藏、性能怎么救、以及那些文档里没有的坑。适合手里已经有一个 .NET 项目想加移动端、或者正在技术选型的人。2. MAUI 的架构边界Handler、生命周期和依赖注入怎么决定项目结构2.1 Handler 机制为什么控件能跨平台但样式不能MAUI 里每个控件都对应一个IView接口真正干活的是每个平台上的ViewHandler。你在 XAML 里写一个Button /Android 上实际创建的是AppCompatButtoniOS 上是UIButtonWindows 上是Button。Handler 的核心职责是把 MAUI 的虚拟视图和原生视图之间的属性同步、事件转发、生命周期管理全部接管。理解这个映射关系是排查界面问题的前提如果你发现某个控件的某个属性在 Android 上有表现、在 iOS 上没反应第一反应不该是怀疑 MAUI 有 bug而是去查这个属性有没有在对应平台的 Handler 里实现映射。Handler 另一个实用意义是没有映射的属性可以自己补。比如 MAUI 官方控件里Border的StrokeShape在早期版本里对圆角的处理不一致社区里常见的做法是写一个自定义RoundBorderHandler继承默认实现后重写SetupContainer和RemoveContainer来替换原生容器视图。这属于进阶玩法但项目做到后期几乎一定会碰到至少一次。// 自定义 Handler 示例让 Button 在 Android 上统一走 Material 样式 public class MaterialButtonHandler : ButtonHandler { protected override Android.Views.View CreatePlatformView() { var view base.CreatePlatformView(); // 这里拿到的是 AppCompatButton可以继续做原生层调整 return view; } public static void Register() { // 替换默认映射注意要在 Microsoft.Maui.Hosting 命名空间下调用 Microsoft.Maui.Hosting.MauiAppBuilderExtensions .ConfigureMauiHandlers(MauiApp.CreateBuilder().Build(), handlers { handlers.AddHandlerButton, MaterialButtonHandler(); }); } }这段代码里最关键的是CreatePlatformView的时机它只在控件第一次被创建时执行如果是列表项里的 ButtonItemTemplate 被回收复用时不会重复走这里。所以凡是要对原生视图做一次性初始化的逻辑放在这个方法是安全的凡是依赖数据变化要更新的逻辑必须放在Map系列方法里或者直接在控件的PropertyChanged里做。初次接触 Handler 的人最容易在这里踩坑后面避坑章节会展开说。2.2 生命周期MAUI 的 Application 和 Page 生命周期不是一一对应的MAUI 的生命周期模型继承了 Xamarin.Forms 的OnStart/OnSleep/OnResume同时也增加了与平台生命周期对接的Window概念。一个被忽略的现实是Application.OnStart不等于首页的OnAppearingOnSleep也不等于 App 退到后台。在 Android 上OnStart对应的是Activity.OnCreate之后的时机在 iOS 上它对应FinishedLaunching。如果你的应用启动逻辑里有读本地缓存 → 请求远端配置 → 初始化导航到首页这样的序列放在哪里非常讲究。推荐的做法是只把不依赖 UI 的轻量初始化放进OnStart把页面相关的放在首页的OnAppearing里并且用protected override而不是订阅事件因为 MAUI 的Page.OnAppearing在模态页弹出和返回时也会被触发。Window的出现解决了之前一个老大难问题多个页面的OnAppearing触发时机不统一无法确定用户真正回到 App的时刻。MAUI 里Window.Created、Window.Resumed、Window.Stopped才是可靠的 App 级前后台切换信号。这里给一个实际用过的初始化序列适用于大部分业务 App阶段调用点适合放什么不建议放什么App 冷启动Application.OnStart日志组件、崩溃上报、DB 迁移、单例服务预创建导航到首页、请求用户隐私数据首次深链接处理Window.Created解析路由参数、检查是否需要登录创建弹窗此时 UI 未就绪每次回到前台Window.Resumed刷新 Token、同步消息角标重新请求定位权限每次退到后台Window.Stopped保存草稿、暂停播放执行网络请求2.3 依赖注入MAUI 里的容器用法比 ASP.NET Core 少一套约束MAUI 模板里自带了一个MauiProgram.CreateMauiApp()里面已经把IServiceCollection暴露出来了。这意味着你不需要再引入第三方容器AddSingleton、AddTransient、AddScoped三个方法的语义和 ASP.NET Core 一致。真正需要形成项目纪律的是Page 也用依赖注入创建。很多项目只在 ViewModel 上用 DIPage 仍然是自己new这就导致 ViewModel 的构造函数里能拿到服务但 Page 的构造函数里拿不到Shell 导航时更传不进去。一个可行的约束是所有 Page 的构造函数里只接收 ViewModel 和导航参数不要在 Page 里new任何服务。Shell 的Routing.RegisterRoute配合Routing.GetOrCreateContentPage可以做到自动从容器里解析页面但 MAUI 默认的Routing机制并不会走 DI 容器需要手动做一层包装。常见做法是写一个ShellRouteFactory在CreateContentPage里从IServiceProvider解析目标页。// 在 MauiProgram.cs 中注册路由和页面 builder.Services.AddTransientDetailPage(); builder.Services.AddTransientDetailViewModel(); // 路由注册时传给工厂方法 Routing.RegisterRoute(detail, new ShellRouteFactory( sp sp.GetRequiredServiceDetailPage())); // ShellRouteFactory 核心逻辑 public class ShellRouteFactory : RouteFactory { private readonly FuncIServiceProvider, Page _factory; public ShellRouteFactory(FuncIServiceProvider, Page factory) _factory factory; public override Element GetOrCreateContentPage(IServiceProvider services) { return _factory(services); } }这个做法的价值不只是解耦。当页面从容器里统一创建时页面和 ViewModel 的构造函数可以收紧参数只暴露真正需要的依赖。项目里经常出现的ViewModel 里塞了十几个服务通常就是从不用 DI 创建页面开始的一旦页面能直接拿服务开发者就会顺手在构造函数里加参数最终一发不可收拾。参数说明上值得注意一点GetOrCreateContentPage的services参数是 Shell 在导航时传入的它拿到的是MauiContext.Services即全局容器所以不能指望它能解析AddScoped范围下的对象。在 MAUI 当前版本里页面没有真正的 Scoped 生命周期写页面注册时统一用AddTransient最稳妥。3. 从模板到可交付MVVM、Shell 导航和数据绑定怎么组织不翻车3.1 MVVM 的最小闭环没有框架的 Command、ObservableObject 和消息机制MAUI 模板自带ObservableObject基类和Command类型它们在CommunityToolkit.Mvvm包里有同名实现模板默认用的是后者。但很多第一次接触 MVVM 的人会混淆两个概念Command负责的是按钮能不能点和点了之后跑什么ObservableObject负责的是属性变化了怎么通知界面。前者是行为后者是状态两者需要配合使用。写完一个[ObservableProperty]标记的字段后必须记得在构造函数里完成初始化否则命令执行时可能拿到 null。实际项目里最容易出问题的是异步命令的并发控制。用户快速连点两次提交按钮如果命令里是一个网络请求第二次点击几乎必然触发重复提交。CommunityToolkit.Mvvm的AsyncRelayCommand默认允许并发执行要限制的话得显式传入AsyncRelayCommandOptions.None或者在命令体开头先判断IsRunning。没有框架的写法是自己在 ViewModel 里维护一个_isBusy标志但状态一多就容易漏。// 一个带并发保护的提交命令 [ObservableProperty] private string userName; [ObservableProperty] private bool isSubmitting; private async Task OnSubmitAsync() { if (IsSubmitting) return; // 防止连点 IsSubmitting true; try { await _api.SubmitAsync(UserName); } finally { IsSubmitting false; } } public ICommand SubmitCommand { get; }注意try/finally里复位IsSubmitting这比提交完成后再赋值更安全因为网络异常时finally也一定会执行。IsSubmitting绑定到按钮的IsEnabled上可以进一步物理禁用按钮客户端校验毕竟只是缓解服务端幂等才是最终兜底。数据绑定的坑通常出现在PropertyChanged没有触发时排查口诀是先看属性是不是[ObservableProperty]标记的再看绑定路径的BindingContext有没有设对最后看x:DataType有没有写错。3.2 Shell 导航路由注册和传参的三种姿势Shell 是 MAUI 默认的导航容器它负责页面栈管理、Tab 结构、导航动画还有一个容易被忽略的能力深链接路由。路由注册写在AppShell.xaml.cs的构造函数里常见写法是Routing.RegisterRoute(detail, typeof(DetailPage))。这个 Route 的命名规则是全局唯一的不能有两个页面注册同一个名字否则运行时才报错排查起来比编译期报错难受得多。Shell 导航的传参与传统Navigation.PushAsync不同GoToAsync有两种传参路径一种是QueryProperty页面接收端用[QueryProperty]特性标记属性另一种是IDictionarystring, object方式传对象。需要强调一个很多人不知道的细节Shell 的GoToAsync传参是一次性的。第一次导航到页面 A 并传了参数页面 A 的[QueryProperty]会收到值当你从 A 返回再重新进入 A 时如果不显式传参上一次的值还在。常见处理办法是在目标页的OnAppearing里清空这些属性或者每次导航都明确传null。// 带参数导航 await Shell.Current.GoToAsync( detail, new Dictionarystring, object { [id] item.Id, [source] list }); // 接收端 [QueryProperty(nameof(ItemId), id)] [QueryProperty(nameof(Source), source)] public partial class DetailPage : ContentPage { public string ItemId { get; set; } public string Source { get; set; } }第二种传参姿势是 Shell 推荐的对象在导航栈里共享制比如把用户选中的整个实体对象传给下一页。这种方式的代价是你必须在AppShell.xaml里给对应 Route 注册ShellContent否则 Shell 只是单纯往栈里压页面对象传递不会生效。第三种姿势是走Routing.GetOrCreateContentPage的依赖注入把参数通过构造函数传给 ViewModel这种方式适合数据需要立刻参与页面初始化的场景QueryProperty的赋值时机在OnNavigatedTo里和构造函数之间有明显的时间差。3.3 CollectionView 性能与绑定模板复用不是免费的CollectionView替代了老的ListView但它的性能优势建立在正确设置ItemsLayout和ItemsSource的前提上。一个反面案例在ItemTemplate里直接写Binding Price, StringFormat{}{0:C}然后在运行时把 200 条数据全部加载进ObservableCollection首页滑动时掉帧明显。标准做法是分页加载RemainingItemsThreshold配合RemainingItemsThresholdReachedCommand做触底加载页面初始只拉第一页 20 条。DataTemplate里尽量少用{Binding}改用x:DataType指定绑定类型这样绑定表达式是编译期生成的省掉反射开销。如果模板内有Image控件务必设置Aspect和合理的Cache策略否则列表滚动时图片解码会占满主线程。更极端的做法是放弃DataTemplate直接在代码里创建ViewCell但这样写的代码很难维护通常只在有明确性能瓶颈且已定位到是绑定开销时做。列表性能排查我一般先做三个验证关掉调试器的XAML 热重载后测试因为热重载会在调试模式下注入额外逻辑把ItemTemplate里的元素逐步删到只剩一个Label看滚动是否有改善这一步能定位是渲染开销还是绑定开销最后检查ItemSizingStrategy.MeasureFirstItem是否启用Uniform模式会拖慢首次渲染速度但如果所有 item 都等宽等高它又是最省算力的选择。4. MAUI 的常见问题与避坑运行时报错、平台差异和调试陷阱4.1 找不到 Default Font Family 与资源解析失败MAUI 在 Windows 上调试时经常报Resource Default Font Family was not found第一反应是资源的键写错了但实际原因多半是Shell的FlyoutBehavior或TabBar的结构里某个ShellContent没有被正确识别。修复方式是在AppShell.xaml里检查每个ShellContent有没有显式指定ContentTemplate不要依赖隐式的页面类型推断。还有一种情况是资源字典的合并顺序问题App.xaml里后合并的字典会覆盖前面的同名键如果某个自定义样式被覆盖成空值字体资源就解析不到。4.2 iOS 模拟器上中文输入框的提交键不触发回到真机没有这个问题。iOS 的Entry.ReturnType和ReturnCommand在模拟器上因为键盘类型变化会出现 ReturnCommand 不触发的现象模拟器里用蓝牙键盘时更明显。解决方式是监听Completed事件它比ReturnCommand稳定。这个坑跨版本复现过多次和 MAUI 版本关系不大本质是模拟器键盘和硬件之间的桥接问题。// 用 Completed 事件替代 ReturnCommand 的稳定写法 entry.Completed OnEntryCompleted; void OnEntryCompleted(object sender, EventArgs e) { // 这里处理搜索/下一项 _viewModel.ExecuteSearchCommand.Execute(null); }4.3 Android 上 Release 包崩溃Debug 包正常典型原因是混淆器或裁剪器把反射调用的成员删掉了。MAUI 默认开启了TrimModepartial部分裁剪模式对它自己是安全的但如果你用了表达式树、动态创建类型、或者通过反射调用私有方法就必须在MauiProgram.cs或csproj里加上[DynamicDependency]特性。另一个常见原因是 Android 的Mono.Android程序集版本不对TargetFramework指定了net8.0-android但 NuGet 包引用了更高版本Release 构建时资源被缩减跳过导致运行时查不到基类构造函数。排查时先看崩溃日志是不是MissingMethodException或TypeLoadException是的话基本可以直接判定和裁剪有关。试着把csproj里TrimMode改成none构建一次如果不再崩溃再回头精确定位反射点。Release 包问题大多数是构建环境里能跑但优化器动了手脚和业务逻辑本身关系很小。4.4 Windows 平台调试时无法部署到模拟器在 Windows 上跑 MAUI 项目目标一般选net8.0-windows10.0.19041.0这个目标跑在 WinUI3 环境下。模拟器指的不是 Android 模拟器而是 Windows 的Windows App SDK部署目标。如果Windows Machine上部署失败先确认Windows App SDK运行时版本是否匹配以及开发模式是否打开。常见报错是Deployment failed原因是 Developer Mode 未开启或已安装的Windows App SDK运行时和项目引用的Microsoft.WindowsAppSDK版本不一致。打开系统设置里的开发者模式即可解决大部分部署失败。4.5 页面频繁 MemoryWarning 导致的随机卡死MAUI 的SoftInput键盘、图片缓存和 WebView 是内存大头。在低端 Android 设备上如果CollectionView的图片没有做缩略图原图直接加载内存涨得非常快。MAUI 的Image只有在设置了HeightRequest/WidthRequest时会压缩到目标尺寸否则按原始分辨率解码。内存警告触发后Android 系统会向 App 发送OnTrimMemoryMAUI 并不会自动释放图片缓存需要手动监控图片控件并清理。// 在 Application 中监听内存警告并清理图片缓存#if ANDROID public override void OnTrimMemory(TrimMemory level) { base.OnTrimMemory(level); if (level TrimMemory.UiHidden) { ImageCache.Shared.Clear(); } } #endif这段代码要注意ImageCache.Shared.Clear()只清理 MAUI 内部缓存不清理你手动加载到内存的ImageSource。标准的图片加载最佳实践是服务端把图片压到合适尺寸再下发客户端仅展示。另一个容易被忽略的是WebView它的原生内存管理失控通常是泄漏最严重的一项释放时直接销毁页面比尝试清缓存的兜底效果更可靠。5. 平台能力接入定位、相机和推送的 MAUI 封装与原生互操作边界5.1 定位权限引发的隐私合规问题怎么绕开定位是最常见的平台能力需求也是新人翻车最多的点。MAUI 的Permissions.LocationWhenInUse在 Android 13 及以上没有特殊问题但在 Android 11 到 12 的机型上如果只声明ACCESS_COARSE_LOCATION而不声明ACCESS_FINE_LOCATION部分厂商 ROM 会弹定位权限未适配提醒。更隐蔽的是Permissions.RequestAsyncPermissions.LocationWhenInUse()返回的PermissionStatus.Denied在用户点击了仅本次允许时会变成Unknown肉眼看到的Denied不是唯一的失败态。真正规范的做法是在调用定位前准备一个权限状态引导页。用户第一次拒绝后第二次触发时不能只调用RequestAsync因为 iOS 上第一次拒绝后再次请求不会弹窗必须跳转系统设置。MAUI 里没有内置跳转设置页的 API常见做法是用Launcher.OpenAsync(new Uri(AppInfo.Current.RequestedTheme AppTheme.Light ? ms-settings:privacy-location : ms-settings:privacy-location))拉起平台设置页。Android 的跳转 Uri 不一样需要用Android.Net.Uri.Parse(package:应用包名)构造和StartActivity。这段平台代码建议收在Platform文件夹里用partial方法在不同平台上分别实现。// 权限状态流转的统一封装忽略具体平台代码 public async Taskbool EnsureLocationPermissionAsync() { var status await Permissions.CheckStatusAsyncPermissions.LocationWhenInUse(); if (status PermissionStatus.Granted) return true; status await Permissions.RequestAsyncPermissions.LocationWhenInUse(); if (status PermissionStatus.Granted) return true; if (status PermissionStatus.Denied DeviceInfo.Current.Platform DevicePlatform.iOS) { // iOS 需要引导到设置页 await Launcher.OpenAsync(AppSettings.LocationSettingUri); return false; } return false; }这里有个细节Android 的Denied不一定是永久拒绝只是这次没同意。你在 Android 判断Denied后如果要引导用户去设置页只会把用户推去打开发者。正确态度是首次拒绝后点击重试再次RequestAsync只有连续拒绝两次以上才引导去设置页。iOS 的定位权限请求还有一个使用期间和精确位置的开关RequestAsync拿到的值无法区分模糊位置和精确位置如果需要高精度定位得在原生层判断CLLocationManager.Accuracy状态。MAUI 的GeolocationAPI 并没有暴露这个粒度属于原生互操作的边界。5.2 相机与原生拍摄界面的差异FilePicker 不等于 CameraMAUI 的MediaPicker.CapturePhotoAsync()在 Android 上调用的是系统相机在 iOS 上调用的是UIImagePickerController两者的返回路径不同但 MAUI 都会转成FileResult看起来一致。坑出在返回的图片可能非常大FileResult.OpenReadAsync拿到的流是大文件原图如果你直接做 Bitmap 解码Android 低端机内存溢出是板板钉钉。处理办法是先读文件信息做降采样后再解码。常见做法是读取一张缩略信息用Exif和BitmapFactory.Options控制采样率这个逻辑在原生平台上写比较麻烦MAUI 的ImageSource.FromStream只负责展示不负责优化内存。所以社区里通常的做法是拍摄完成后先压缩到 1280 或 1920 的宽边然后拿到压缩后的流再做后续上传或展示。// 拍摄照片后压缩再展示的标准路径 var photo await MediaPicker.CapturePhotoAsync(); if (photo null) return; using var sourceStream await photo.OpenReadAsync(); var resizedBytes await ImageCompressor.ResizeAsync(sourceStream, 1280, 90); _previewImage.Source ImageSource.FromStream(() new MemoryStream(resizedBytes));ImageCompressor是自定义的跨平台图片压缩辅助类Android 上用BitmapFactory采样 CompressFormat.Jpeg输出iOS 上用ImageIO或UIKit绘制到目标尺寸后导出 Jpeg。核心点是采样 尺寸限制 质量压缩三者缺一不可只压缩质量不降分辨率内存占用降不下来只降分辨率不控制采样解码时原图已经进内存降采样白搭。相机场景的另一个坑是CapturePhotoAsync()在 Android 上要求有FileProvider配置模板里没有现成的file_paths.xml和FileProvider声明不加会在运行时直接黑屏或抛FileUriExposedException。需要在AndroidManifest.xml里加provider节点并在资源里添加对应的 xml 文件。5.3 推送通知到达回调MAUI 层处理点击事件和原生层初始化没有先后几乎所有推送 SDK如极光、个推或厂商通道都要求先初始化原生 SDK拿到设备 token 后再绑定别名和标签。MAUI 项目里如果把初始化放在Application.OnStart在 Android 上会碰到Activity尚未创建完毕、初始化时拿不到Context的问题。正确时机是Window.Created之后或者直接在主Activity的OnCreate里调用。iOS 上则要注意AppDelegate.FinishedLaunching里注册推送回调的顺序卸载和重装时调试推送时常遇收不到的情况多半是 token 没有重新绑定。实现上建议把推送封装成一个跨平台服务接口IPushService在Platforms/Android和Platforms/iOS下分别实现 Android 和 iOS 的注册、注销、接收消息。MAUI 层只依赖这个接口配合 DI 注册AddSingletonIPushService, AndroidPushService()。这不是 MAUI 特有的架构但到了 MAUI 里由于Application类本身是跨平台的你一不小心就会把平台 SDK 的初始化代码写进共享代码里等测试到不同端才发现平台框架已经崩了。推送点击跳转页面的路径建议用 Shell 路由传参而不是直接Navigation.PushAsync。点击通知时 App 可能处于三种状态冷启动、后台存活、前台活跃。冷启动时 Shell 页面栈还没有建立此时必须等Window的Created完成后再执行导航否则会报Shell.Current为空。处理方式是先把推送消息缓存在静态变量里等 Shell 就绪后消费缓存执行跳转。这个缓存 延时消费模式对深链接、扫码跳转同样适用。推送的 token 上报也有讲究。厂商通道的 token 和 MAUI 里拿到的 token 不是同一个东西厂商通道要的是各自 SDK 生成的regId/tokenMAUI 里的DeviceInfo或推送插件提供的 token 只在应用内有效。做推送运营活动时一定要把厂商通道 token 的更新回调对接到服务端否则用户换机或重装后推送永远发到旧设备。跨平台封装的推送服务要在 SDK 回调里同步更新服务端的绑定关系而不是等 App 下次启动时再绑。5.4 原生互操作的几个策略不把平台代码写进共享项目MAUI 项目天然有四个平台文件夹平台差异代码的最好归宿是那里。但是项目做大了平台代码会膨胀共享项目里的接口就变成了约束平台实现的规范。这里定义一套标准共享层只出现public interface ICameraService { Taskbyte[] TakePhotoAsync(); }这种契约平台层实现ICameraService而共享层通过IServiceProvider.GetRequiredServiceICameraService()消费。平台层内部可以自由使用原生 API不用为跨平台兼容做任何妥协。原生互操作的高级玩法是MauiWinUIApplication或 Android 的AndroidX库回调注入 MAUI 的IServiceCollection但这需要MauiContext的桥接。以 Android 为例MAUI 提供了一个Platform.CurrentActivity静态入口你可以在原生代码里拿到当前Activity但Activity的生命周期和 MAUIWindow不同步Platform.CurrentActivity在 Application 启动早期经常是 null。解决方法是注册IActivityResultCallback这个接口的回调可以等到 Activity 创建完成后再执行。多任务场景下原生 SDK 的回调线程不是 UI 线程更新 MAUI 绑定集合时不要直接操作要走MainThread.BeginInvokeOnMainThread。这块是很多混合开发项目崩溃的根源跨线程更新 UI 在 MAUI 里不会像 WinForms 那样直接抛异常而是表现为随机闪退或数据错乱排查成本极高。另一个值得强调的边界是 MAUI 的DeviceDisplay和DeviceInfo的线程安全。DeviceDisplay.KeepScreenOn属性在 Android 上影响的是Window的Flags如果在原生代码里同时设置Window的其他 flag顺序不当会导致屏幕常亮失效。这类跨层交互不好调试建议项目里建立统一走 MAUI API禁止在平台层直接操作 Window/Activity 状态的规则实在要动也要在注释里写明 MAUI API 对应的原生行为。到了性能优化的验证阶段我的习惯是按三个层次验收第一层看启动时间用System.Diagnostics.Stopwatch在AppDelegate和MainActivity里分别埋点第二层看列表滑动帧率用Profile工具抓 trace第三层看内存增长趋势重点检查页面销毁后ObservableCollection有没有被强引用。这三个指标都过了再谈上线。.NET MAUI 这个框架走到今天已经不缺文档和教程缺的是把项目真正交给用户跑起来时那些没人写的细节。开发跨平台 App 和写后端服务最大的不同是你永远无法在 Mac 上完整预测 Android 真机的行为反过来也一样。我自己的习惯是把平台差异当成一等公民在每个功能的开发前先问一句这个逻辑在 Android 和 iOS 上会有什么不同表现然后刻意去翻两端的原生文档而不是等 QA 报 bug。很多东西像Permissions的返回值、通知点击的时序真机上的表现和模拟器截然不同早点用真机跑养成这个习惯能帮你省掉一大半的深夜排查时间。希望这篇实战笔记能在你从敲通了示例到交付到应用商店的路上少绕几个弯帮到你。本文还有配套的精品资源点击获取