maui是全新架构跨平台ui框架，需严格遵循其生命周期、依赖注入和平台配置规范；入口为mauiprogram.cs，服务注册、路由配置、原生权限声明等必须按maui方式实现，否则将引发白屏、资源缺失、热重载失效等问题。
MAUI 不是“升级版 Xamarin.Forms”，而是全新架构的跨平台 UI 框架，直接用它开发移动应用没问题，但必须按它的生命周期、依赖注入和平台特定逻辑组织代码——否则 iOS 启动白屏、Android 资源找不到、热重载失效都是常态。
MAUI 项目结构里 MauiProgram.cs 是唯一入口，别再写 App.xaml.cs 初始化逻辑
旧 Xamarin.Forms 习惯在 App.xaml.cs 的构造函数里注册服务或初始化数据库，MAUI 已废弃该模式。所有服务注册、配置加载、字体/图标注入，必须统一收口到 MauiProgram.CreateMauiApp() 中。
-
MauiAppBuilder.Services.AddSingleton<idataservice sqlitedataservice>()</idataservice>才是注册单例的正确位置 - 平台专属初始化（如 Android 的
Microsoft.Maui.Essentials.Platform.Init()）已由框架自动调用，手动调用会触发重复初始化异常 - 如果需要在启动时读取
appsettings.json，得用builder.Configuration.AddJsonFile("appsettings.json")，且文件Build Action必须设为MauiAsset
页面导航必须用 Shell 或 NavigationPage，PushAsync 不能直接调用
MAUI 默认模板启用 Shell，所有页面跳转应通过路由注册 + Shell.Current.GoToAsync("//pagekey")。直接 new 页面后调用 Navigation.PushAsync(new Page()) 在 Shell 模式下会静默失败，且 iOS 上可能卡死。
- 路由注册必须在
MauiProgram.cs中完成：builder.ConfigureMauiHandlers(handlers => handlers.AddHandler<mycustomview mycustomviewhandler>());</mycustomview>不管用，路由要用Routing.RegisterRoute("detail", typeof(DetailPage)); - 非 Shell 场景（比如纯
NavigationPage）需在App.xaml.cs中设置MainPage = new NavigationPage(new HomePage());，且后续所有跳转必须基于这个根NavigationPage实例 -
GoToAsync的 URI 支持//（绝对路径）、/（相对路径）、..（返回上层），但不支持查询参数自动绑定，需手动解析Shell.Current.State.Location.QueryString
访问原生 API 用 Microsoft.Maui.Essentials，但 iOS 需额外配 Info.plist，Android 需改 AndroidManifest.xml
Permissions.RequestAsync<permissions.locationwheninuse>()</permissions.locationwheninuse> 这类调用看似简单，实际运行时会因权限声明缺失直接抛 Java.Lang.SecurityException（Android）或静默拒绝（iOS），错误信息里不会提示缺哪项配置。
- iOS：必须在
Platforms/iOS/Info.plist里补全键值对，例如定位要加<key>NSLocationWhenInUseUsageDescription</key><string>需要访问位置以显示附近门店</string> - Android：在
Platforms/Android/AndroidManifest.xml的<application></application>外添加权限声明，如<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"></uses-permission> -
Preferences.Set("token", value)在模拟器上正常，真机可能因沙盒路径变化写入失败，建议改用SecureStorage.SetAsync("token", value)存敏感数据
自定义渲染器已被弃用，Handler 替代方案必须显式注册且注意泛型约束
想改 Android 上 Button 的圆角或 iOS 上 Entry 的边框颜色？别找 ExportRenderer——MAUI 用 IViewHandler 和平台专属 Handler 类替代，但注册方式和类型匹配极严格。
- 必须继承
ButtonHandler（不是ViewHandler<button abutton></button>），并重写ConnectHandler或DisconnectHandler - 注册时写成
handlers.AddHandler<button custombuttonhandler>()</button>，漏掉泛型参数或类型不匹配会导致运行时回退到默认样式，无任何警告 - iOS 的
UIButton和 Android 的MaterialButton属性名差异大，比如圆角：iOS 用Control.Layer.CornerRadius，Android 要改Control.Background的ShapeAppearanceModel
MAUI 的“一次编写、多端运行”成立的前提是接受它的约束：Shell 导航模型、平台配置硬性要求、Handler 注册机制。绕开这些去套用 Xamarin.Forms 经验，问题只会更隐蔽——比如热重载成功但界面不更新，往往是因为 Handler 没在 MauiProgram.cs 正确注册，而不是代码写错了。
