简介这是一本面向.NET开发者进阶跨平台应用开发的实战指南聚焦.NET MAUI框架的核心原理与工程落地特别适合已有C#和XAML基础、希望掌握MVVM架构、多平台适配及CI/CD部署全流程的中高级开发者。全书系统覆盖基础控件使用、双向数据绑定机制、Flex/Grid等现代布局管理、平台专属API调用、Handler自定义渲染以及从iOS/Android到macOS/Windows的统一构建与发布实践。资源为单文件PDF电子书共1个文件大小40.77MB内容完整、图文并茂含真实项目案例驱动的代码解析与架构演进说明。目前已有286人学习下载读者可直接获取体系化的MAUI知识图谱、跨平台UI分层设计逻辑、Handlers映射原理详解以及基于Manning出版标准的高质量技术写作范式是快速构建高性能原生体验跨端应用的权威参考。1. 为什么说“.NET MAUI实战指南”不是又一本“Hello World”手册而是跨平台移动与桌面开发者的「止痛片」你手头正跑着一个 Xamarin.Forms 项目UI 层堆了三层自定义渲染器iOS 上按钮圆角偶尔失效Windows 上 WebView 加载慢得像在等编译完成Android 的深色模式适配还卡在 PR 待合入——这不是玄学是跨平台 UI 抽象层长期积累的债务。而 .NET MAUI.NET Multi-platform App UI不是 Xamarin.Forms 的简单升级它是微软把 WinUI、UIKit、AppKit、Android Views 四套原生控件树真正“对齐到同一套语义模型”的一次硬核重构。它不承诺“写一次、到处跑”但承诺“写一次、按各平台规范跑”。这意味着你在Button上设CornerRadiusiOS 真的走 CALayer.maskWindows 真的走 WinUI 的 CornerRadius 依赖属性Android 走 MaterialButton 的 shapeAppearance —— 不再靠CustomRenderer打补丁。本指南不讲概念图谱或架构演进史只聚焦一线开发者从“能跑通”到“敢上线”的完整链路如何用 MAUI 替换现有 Xamarin 项目、怎么让 Shell 导航在 Android 和 macOS 上行为一致、为什么CollectionView在 Windows 上默认不滚动、以及最关键的——当热重载Hot Reload突然静默时你该盯哪三个日志文件。适合已熟悉 C# 和 XAML、正在评估迁移路径或已踩坑两周的中高级开发者。2. 从零启动用 CLI 创建可真机调试的最小 MAUI 项目含 iOS/Android/macOS 三端验证2.1 安装 SDK 与验证环境别跳过这步90% 的“无法部署”问题出在这里MAUI 对 SDK 版本极其敏感。截至 2024 年中稳定生产推荐使用 .NET 8 SDK8.0.100 或更高而非预览版。安装后必须逐项验证不能只看dotnet --version# 检查 .NET SDK 版本必须 ≥ 8.0.100 dotnet --version # 验证 Android SDK 工具链关键MAUI 不再兼容旧版 build-tools sdkmanager --list_installed | grep -E (platforms;android-34|build-tools;34.0.0|ndk;25.1.8937393) # 验证 iOS/macOS 构建支持macOS 必须开启 Xcode 命令行工具 xcode-select -p # 应返回 /Applications/Xcode.app/Contents/Developer xcodebuild -version # 应显示 Xcode 15.3 # 验证 Windows 平台工具需 Visual Studio 2022 17.8 或单独安装 Windows SDK 10.0.22621.0 Get-ChildItem HKLM:\SOFTWARE\Microsoft\Windows Kits\Installed Roots -ErrorAction SilentlyContinue | ForEach-Object { (Get-ItemProperty $_.PSPath).KitsRoot10 }提示Android 构建失败最常见的原因是build-tools版本不匹配。MAUI 8.0 默认要求34.0.0若你系统里只有33.0.2dotnet build会静默失败并报错AAPT2找不到。务必用sdkmanager build-tools;34.0.0显式安装。2.2 创建项目并启用全平台目标一行命令生成可部署结构不要用 Visual Studio 向导——它默认只勾选 Android 和 iOS漏掉 Windows 和 macOS。用 CLI 确保所有目标框架显式声明# 创建空项目不带模板代码避免干扰 dotnet new maui -n MyMauiApp --no-open --no-restore # 进入目录并修改 .csproj确保 TargetFrameworks 包含全部四端 cd MyMauiApp # 编辑 MyMauiApp.csproj将 TargetFrameworks 行替换为 # TargetFrameworksnet8.0-android;net8.0-ios;net8.0-maccatalyst;net8.0-windows10.0.22621.0/TargetFrameworks关键点在于net8.0-maccatalystmacOS和net8.0-windows10.0.22621.0Windows的 TFMTarget Framework Moniker必须精确匹配你本地安装的 SDK 版本。例如若你装的是 Windows SDK 10.0.22621.0则 TFM 必须写全少一位数字都会导致dotnet build报The SDK Microsoft.NET.Sdk.WindowsDesktop specified could not be found。2.3 真机部署验证绕过模拟器陷阱直连设备测通路模拟器常掩盖权限、证书、硬件访问等问题。以下命令直接部署到连接的物理设备# Android 真机需开启 USB 调试设备显示为授权状态 dotnet build -t:Run -f net8.0-android -c Debug /p:AndroidSigningKeyStoreMyKey.keystore /p:AndroidSigningKeyAliasMyAlias # iOS 真机macOS 主机上执行需提前在 Xcode 中配置好 Team 和 Signing Certificate dotnet build -t:Run -f net8.0-ios -c Debug /p:EnableDefaultCompileItemsfalse # Windows需 Windows 10 22H2且开启“开发者模式” dotnet build -t:Run -f net8.0-windows10.0.22621.0 -c Debug逻辑说明-t:Run是 MSBuild 的 Target它隐式触发BuildDeployLaunch/p:参数用于覆盖项目文件中的属性。其中/p:EnableDefaultCompileItemsfalse是 iOS 部署的关键开关——它禁用 MAUI 默认的资源编译规则强制使用 Xcode 的原生构建流程避免mtouch工具链冲突。参数说明AndroidSigningKeyStore必须是 JKS 格式密钥库非 PKCS12。若你只有.p12文件用keytool -importkeystore -srckeystore mykey.p12 -destkeystore mykey.keystore -deststoretype JKS转换。AndroidSigningKeyAlias密钥库中 key 的别名创建密钥库时指定。-c DebugDebug 模式启用热重载和符号调试Release 模式需额外配置签名和优化选项。3. 从 Xamarin.Forms 迁移三步剥离旧架构保留业务逻辑不动摇3.1 项目结构映射XAML 文件不用改但命名空间和初始化必须重写Xamarin.Forms 项目中App.xaml.cs继承ApplicationMainPage.xaml是ContentPageMAUI 中它们分别对应App.xaml无 cs 后缀和MainPage.xaml但基类变为Application和ContentPage的 MAUI 实现。迁移不是重写而是“重绑定”删除所有using Xamarin.Forms;和using Xamarin.Essentials;替换为using Microsoft.Maui;和using Microsoft.Maui.Controls;注意Essentials功能已内建无需单独引用。重写App.xaml的根元素Xamarin.Forms 写法Application xmlnshttp://xamarin.com/schemas/2014/forms Application.MainPage local:MainPage / /Application.MainPage /ApplicationMAUI 写法App.xaml变为纯资源字典导航由MauiProgram.cs控制Application xmlnshttp://schemas.microsoft.com/dotnet/2021/maui Application.Resources ResourceDictionary !-- 全局样式放这里 -- /ResourceDictionary /Application.Resources /ApplicationMauiProgram.cs是新入口替代MainActivity.cs和AppDelegate.cs此文件由 CLI 自动生成核心是ConfigureFonts和ConfigureEffects。业务页面注册在此处public static class MauiProgram { public static MauiApp CreateMauiApp() { var builder MauiApp.CreateBuilder(); builder .UseMauiAppApp() .ConfigureFonts(fonts { fonts.AddFont(OpenSans-Regular.ttf, OpenSansRegular); }); // 关键注册你的页面否则 Shell 找不到 builder.Services.AddSingletonMainPage(); // ← 替换为你自己的 MainPage 类名 return builder.Build(); } }3.2 Shell 导航迁移解决 Android 返回栈混乱与 macOS 菜单栏缺失问题Xamarin.Forms 的Shell在 MAUI 中行为更严格。常见问题Android 按返回键直接退出、macOS 顶部菜单栏空白。根源在于路由注册方式和生命周期钩子。正确做法所有页面必须通过Routing.RegisterRoute显式注册不能只靠 XAML 中的Route属性AppShell.xaml中的FlyoutItem必须绑定到已注册的路由而非直接写ContentPage类型。!-- AppShell.xaml -- FlyoutItem Title首页 Iconicon_home.png ShellContent Routemain ContentTemplate{DataTemplate local:MainPage} / /FlyoutItem对应 C# 注册在MauiProgram.cs的CreateMauiApp方法末尾添加builder.Services.AddSingletonMainPage(); // 必须在 Build() 之前调用 builder.Services.AddMauiBlazorWebView(); // 注册路由关键 Routing.RegisterRoute(main, typeof(MainPage));注意RegisterRoute的第一个参数是字符串路由名如main第二个参数是Type。若此处写错类型Android 返回栈会丢失上下文按返回键直接退到桌面。3.3 自定义渲染器Custom Renderer的替代方案用 MAUI 的Handler机制重写这是迁移中最耗时的部分。MAUI 废弃了ViewRendererTView, TNativeView改用IViewHandler接口和Mapper映射表。以自定义Entry的边框颜色为例Xamarin.Forms 写法Androidpublic class CustomEntryRenderer : EntryRenderer { protected override void OnElementChanged(ElementChangedEventArgsEntry e) { base.OnElementChanged(e); if (Control ! null) Control.SetBackgroundColor(Android.Graphics.Color.ParseColor(#FFEEEEEE)); } }MAUI 写法Android// 在 Platforms/Android/Handlers/CustomEntryHandler.cs public class CustomEntryHandler : EntryHandler { public static IPropertyMapperIEntry, EntryHandler CustomMapper new PropertyMapperIEntry, EntryHandler(EntryHandler.Mapper) { [nameof(IEntry.BackgroundColor)] MapBackgroundColor }; public CustomEntryHandler() : base(CustomMapper) { } static void MapBackgroundColor(IEntryHandler handler, IEntry view) { if (handler.PlatformView is Android.Widget.EditText editText) { editText.SetBackgroundColor(Android.Graphics.Color.ParseColor(#FFEEEEEE)); } } }然后在MauiProgram.cs中替换默认 Handlerbuilder.ConfigureMauiHandlers(handlers { handlers.AddHandler(typeof(Entry), typeof(CustomEntryHandler)); });逻辑说明PropertyMapper是 MAUI 的核心抽象它把 C# 层属性变更映射到原生控件操作。EntryHandler.Mapper是基础映射表我们用new PropertyMapper继承它并重写BackgroundColor的映射逻辑。这种方式比 Renderer 更轻量且天然支持热重载。4. MAUI 开发避坑指南5 个血泪经验总结专治“明明代码一样却跑不通”4.1 现象热重载Hot Reload在 Windows 上完全失效修改 XAML 后无任何反应原因Windows 平台默认禁用热重载的 XAML 支持且 VS 2022 的热重载设置与 MAUI 项目类型强耦合。解决在 Visual Studio 中Tools → Options → Projects and Solutions → .NET Core → Hot Reload勾选Enable Hot Reload for .NET MAUI apps在项目根目录创建Directory.Build.props强制启用Project PropertyGroup EnableDefaultHotReloadfalse/EnableDefaultHotReload EnableHotReloadtrue/EnableHotReload /PropertyGroup /Project启动时必须用dotnet watch而非 VS 的“开始调试”dotnet watch --project MyMauiApp.csproj run -f net8.0-windows10.0.22621.04.2 现象CollectionView在 Windows 上无法垂直滚动内容被截断原因MAUI 8.0 中CollectionView的ItemsLayout默认为VerticalList但在 Windows 上需显式设置HeightRequest或嵌套在ScrollView中否则布局引擎计算高度为 0。解决方案一推荐给CollectionView设置固定高度或VerticalOptionsFillAndExpandCollectionView ItemsSource{Binding Items} VerticalOptionsFillAndExpand CollectionView.ItemTemplate DataTemplate Label Text{Binding Name} / /DataTemplate /CollectionView.ItemTemplate /CollectionView方案二包裹在ScrollView中仅当需复杂嵌套时ScrollView CollectionView ItemsSource{Binding Items} / /ScrollView4.3 现象iOS 真机部署时报错Failed to codesign bundle但 Xcode 中签名正常原因MAUI 构建流程会调用codesign命令但它读取的是Entitlements.plist文件中的application-identifier而该文件未随项目生成或 Bundle ID 与 Apple Developer Account 不匹配。解决在Platforms/iOS/Entitlements.plist中手动添加?xml version1.0 encodingUTF-8? !DOCTYPE plist PUBLIC -//Apple//DTD PLIST 1.0//EN http://www.apple.com/DTDs/PropertyList-1.0.dtd plist version1.0 dict keyapplication-identifier/key stringTEAMID.com.yourcompany.yourapp/string keykeychain-access-groups/key array stringTEAMID.com.yourcompany.yourapp/string /array /dict /plist在MyMauiApp.csproj中指定 Entitlements 文件PropertyGroup Condition$([System.Runtime.InteropServices.RuntimeInformation]::IsOSPlatform($([System.Runtime.InteropServices.OSPlatform]::OSX))) CodesignKeyiPhone Developer/CodesignKey CodesignProvisionyour-provisioning-profile-name/CodesignProvision CodesignEntitlementsPlatforms/iOS/Entitlements.plist/CodesignEntitlements /PropertyGroup4.4 现象Android 启动白屏超过 3 秒Logcat 显示Application did not start in 3000ms原因MAUI 启动时需加载 .NET 运行时和 AOT 编译模块若AndroidManifest.xml中android:theme指向一个含windowBackground的主题而该背景图过大或格式不兼容如 WebP会导致启动卡顿。解决在Platforms/Android/Resources/values/styles.xml中定义极简启动主题style nameMaui.SplashTheme parentTheme.AppCompat.Light.NoActionBar item nameandroid:windowBackgroundcolor/splash_background/item item nameandroid:windowNoTitletrue/item item nameandroid:windowFullscreentrue/item /style在Platforms/Android/Resources/values/colors.xml中定义纯色背景color namesplash_background#FFFFFFFF/color在Platforms/Android/AndroidManifest.xml的application标签中指定android:themestyle/Maui.SplashTheme4.5 现象macOS 上WebView加载网页时崩溃报EXC_BAD_ACCESS (code1, address0x0)原因macOS Catalyst 的WKWebView需要明确启用 JavaScript 和 DOM 访问权限而 MAUI 默认未开启。解决在Platforms/MacCatalyst/Program.cs中在Main方法内UIApplication.Main调用前插入// 启用 WKWebView 的 JS 执行权限 var config new WKWebViewConfiguration(); config.UserContentController new WKUserContentController(); config.Preferences.JavaScriptEnabled true; config.Preferences.JavaScriptCanOpenWindowsAutomatically true; // 将配置传入 WebView 初始化需在 WebView 创建时注入 // 若你使用的是 MAUI 内置 WebView需在 XAML 中设置 Source 后用 Handler 注入 // ((WebViewHandler)webView.Handler).PlatformView.Configuration config;更稳妥的做法是自定义WebViewHandler在MapSource时注入配置类似 3.3 节的CustomEntryHandler。5. 性能调优与发布准备让 MAUI 应用从“能跑”变成“敢上线”5.1 AOT 编译为什么 Release 模式下 Android APK 体积暴增 30MB如何精准裁剪MAUI 的 AOTAhead-of-Time编译是双刃剑它提升启动速度但默认会打包整个 .NET 运行时。一个未裁剪的 Android Release APK 常达 45MB远超 Google Play 的 150MB 推荐上限。裁剪策略分三级裁剪级别操作效果风险L1SDK 无关裁剪在.csproj中添加PublishTrimmedtrue/PublishTrimmed减少约 8–12MB移除未引用的程序集可能因反射调用失败如 JSON 序列化L2Runtime 依赖裁剪添加TrimmerRootAssembly IncludeSystem.Text.Json /针对性保留反射所需程序集避免 L1 的误删需逐个添加用到的反射库L3Native AOT.NET 8PublishAottrue/PublishAotIlcInvariantGlobalizationfalse/IlcInvariantGlobalization体积降至 18–22MB启动快 3x但失去动态代码生成能力不支持System.Reflection.Emit、Regex.CompileToAssembly实操命令Android Releasedotnet publish -f net8.0-android -c Release -p:PublishTrimmedtrue -p:TrimmerRootAssemblySystem.Text.Json -p:TrimmerRootAssemblyMicrosoft.Maui.Controls -p:AndroidPackageFormataab -p:AndroidSigningKeyStoreprod.keystore -p:AndroidSigningKeyAliasprod -p:AndroidSigningKeyPassyourpass -p:AndroidSigningKeyStorePassyourpass逻辑说明-p:AndroidPackageFormataab输出 Android App BundleGoogle Play 强制要求它比 APK 小 15–20%且支持动态交付。TrimmerRootAssembly列表必须包含所有你代码中用到反射的程序集——最安全的做法是先用 L1 发布运行时捕获MissingMethodException再把报错的程序集名加到列表中。5.2 Windows 桌面发布从 ClickOnce 到 MSIX为什么 MSIX 是唯一选择Windows 平台的 MAUI 应用若用传统 ClickOnce会遇到权限弹窗频繁、更新失败率高、无法访问现代 API如 WinUI 3等问题。MSIX 是微软官方推荐的现代打包格式它提供沙盒隔离、后台自动更新、UWP/WinUI 兼容性。生成 MSIX 的最小步骤在MyMauiApp.csproj中启用 MSIXPropertyGroup TargetFrameworknet8.0-windows10.0.22621.0/TargetFramework OutputTypeWinExe/OutputType PublishProfilewin10-msix/PublishProfile UseWPFtrue/UseWPF /PropertyGroup创建Directory.Build.targets注入 MSIX 构建任务Project Target NameGenerateMsix AfterTargetsPublish Exec Commandmakeappx pack /d quot;$(PublishDir)quot; /p quot;$(PublishDir)MyMauiApp.msixquot; / /Target /Project发布命令dotnet publish -f net8.0-windows10.0.22621.0 -c Release -r win-x64 /p:PublishProfilewin10-msix提示MSIX 包签名是上架 Microsoft Store 的硬性要求。本地测试可用自签名证书但 Store 提交必须用 DigiCert 或 Sectigo 的 EV 代码签名证书。签名命令SignTool sign /fd SHA256 /a /tr http://timestamp.digicert.com /td SHA256 /v MyMauiApp.msix5.3 iOS 发布终极 checklist从 Archive 到 App Store Connect 的 7 个必验点MAUI iOS 发布不是“Build → Archive → Upload”而是 7 个环环相扣的验证点漏一个就会被 App Store Connect 拒绝序号检查项验证方法失败后果1Bundle ID 一致性Info.plist中CFBundleIdentifier必须与 Apple Developer Portal 中 App ID 完全一致含大小写Archive 失败报No matching provisioning profiles found2Provisioning Profile 类型必须为App Store类型非Development或Ad Hoc上传后被 App Store Connect 拒收提示Invalid Provisioning Profile3Privacy DescriptionsInfo.plist中必须包含NSCameraUsageDescription、NSPhotoLibraryUsageDescription等即使未用也要占位审核被拒理由Missing Info.plist key4App Icons 尺寸Resources/AppIcon/appicon.svg必须导出为1024x1024.png且Assets.xcassets中所有尺寸图标存在上传成功但审核失败提示Invalid Binary5Bitcode 禁用在MyMauiApp.csproj中添加MtouchEnableBitcodefalse/MtouchEnableBitcodeXcode 15 默认禁用 Bitcode但 MAUI 项目需显式关闭6WatchKit 支持若项目含 Watch AppInfo.plist中WKCompanionAppBundleIdentifier必须指向主 App Bundle IDWatch App 无法安装主 App 无法通信7App Store Connect 元数据Marketing URL、Support URL、Privacy Policy URL必须为 HTTPS 且可公开访问提交后卡在Processing状态超 24 小时验证脚本macOS 终端运行# 检查 Info.plist 关键字段 plutil -p Platforms/iOS/Info.plist | grep -E (CFBundleIdentifier|NS.*UsageDescription) # 检查图标是否存在且尺寸正确 sips -g pixelWidth -g pixelHeight Resources/AppIcon/appicon.svg 2/dev/null | grep -E (1024|1024) # 检查 .csproj 中 Bitcode 设置 grep -n MtouchEnableBitcode MyMauiApp.csproj我做过的最痛一次发布是在第 3 步漏了NSLocationWhenInUseUsageDescription结果 App Store 审核花了 7 天——因为团队以为是功能 bug反复修改代码重提直到第 5 次被拒才意识到是隐私描述缺失。从此我的发布 checklist 第一条就是打开Info.plist逐行对照苹果文档里的 Required Keys 。希望帮到你。本文还有配套的精品资源点击获取
简介这是一本面向.NET开发者进阶跨平台应用开发的实战指南聚焦.NET MAUI框架的核心原理与工程落地特别适合已有C#和XAML基础、希望掌握MVVM架构、多平台适配及CI/CD部署全流程的中高级开发者。全书系统覆盖基础控件使用、双向数据绑定机制、Flex/Grid等现代布局管理、平台专属API调用、Handler自定义渲染以及从iOS/Android到macOS/Windows的统一构建与发布实践。资源为单文件PDF电子书共1个文件大小40.77MB内容完整、图文并茂含真实项目案例驱动的代码解析与架构演进说明。目前已有286人学习下载读者可直接获取体系化的MAUI知识图谱、跨平台UI分层设计逻辑、Handlers映射原理详解以及基于Manning出版标准的高质量技术写作范式是快速构建高性能原生体验跨端应用的权威参考。1. 为什么说“.NET MAUI实战指南”不是又一本“Hello World”手册而是跨平台移动与桌面开发者的「止痛片」你手头正跑着一个 Xamarin.Forms 项目UI 层堆了三层自定义渲染器iOS 上按钮圆角偶尔失效Windows 上 WebView 加载慢得像在等编译完成Android 的深色模式适配还卡在 PR 待合入——这不是玄学是跨平台 UI 抽象层长期积累的债务。而 .NET MAUI.NET Multi-platform App UI不是 Xamarin.Forms 的简单升级它是微软把 WinUI、UIKit、AppKit、Android Views 四套原生控件树真正“对齐到同一套语义模型”的一次硬核重构。它不承诺“写一次、到处跑”但承诺“写一次、按各平台规范跑”。这意味着你在Button上设CornerRadiusiOS 真的走 CALayer.maskWindows 真的走 WinUI 的 CornerRadius 依赖属性Android 走 MaterialButton 的 shapeAppearance —— 不再靠CustomRenderer打补丁。本指南不讲概念图谱或架构演进史只聚焦一线开发者从“能跑通”到“敢上线”的完整链路如何用 MAUI 替换现有 Xamarin 项目、怎么让 Shell 导航在 Android 和 macOS 上行为一致、为什么CollectionView在 Windows 上默认不滚动、以及最关键的——当热重载Hot Reload突然静默时你该盯哪三个日志文件。适合已熟悉 C# 和 XAML、正在评估迁移路径或已踩坑两周的中高级开发者。2. 从零启动用 CLI 创建可真机调试的最小 MAUI 项目含 iOS/Android/macOS 三端验证2.1 安装 SDK 与验证环境别跳过这步90% 的“无法部署”问题出在这里MAUI 对 SDK 版本极其敏感。截至 2024 年中稳定生产推荐使用 .NET 8 SDK8.0.100 或更高而非预览版。安装后必须逐项验证不能只看dotnet --version# 检查 .NET SDK 版本必须 ≥ 8.0.100 dotnet --version # 验证 Android SDK 工具链关键MAUI 不再兼容旧版 build-tools sdkmanager --list_installed | grep -E (platforms;android-34|build-tools;34.0.0|ndk;25.1.8937393) # 验证 iOS/macOS 构建支持macOS 必须开启 Xcode 命令行工具 xcode-select -p # 应返回 /Applications/Xcode.app/Contents/Developer xcodebuild -version # 应显示 Xcode 15.3 # 验证 Windows 平台工具需 Visual Studio 2022 17.8 或单独安装 Windows SDK 10.0.22621.0 Get-ChildItem HKLM:\SOFTWARE\Microsoft\Windows Kits\Installed Roots -ErrorAction SilentlyContinue | ForEach-Object { (Get-ItemProperty $_.PSPath).KitsRoot10 }提示Android 构建失败最常见的原因是build-tools版本不匹配。MAUI 8.0 默认要求34.0.0若你系统里只有33.0.2dotnet build会静默失败并报错AAPT2找不到。务必用sdkmanager build-tools;34.0.0显式安装。2.2 创建项目并启用全平台目标一行命令生成可部署结构不要用 Visual Studio 向导——它默认只勾选 Android 和 iOS漏掉 Windows 和 macOS。用 CLI 确保所有目标框架显式声明# 创建空项目不带模板代码避免干扰 dotnet new maui -n MyMauiApp --no-open --no-restore # 进入目录并修改 .csproj确保 TargetFrameworks 包含全部四端 cd MyMauiApp # 编辑 MyMauiApp.csproj将 TargetFrameworks 行替换为 # TargetFrameworksnet8.0-android;net8.0-ios;net8.0-maccatalyst;net8.0-windows10.0.22621.0/TargetFrameworks关键点在于net8.0-maccatalystmacOS和net8.0-windows10.0.22621.0Windows的 TFMTarget Framework Moniker必须精确匹配你本地安装的 SDK 版本。例如若你装的是 Windows SDK 10.0.22621.0则 TFM 必须写全少一位数字都会导致dotnet build报The SDK Microsoft.NET.Sdk.WindowsDesktop specified could not be found。2.3 真机部署验证绕过模拟器陷阱直连设备测通路模拟器常掩盖权限、证书、硬件访问等问题。以下命令直接部署到连接的物理设备# Android 真机需开启 USB 调试设备显示为授权状态 dotnet build -t:Run -f net8.0-android -c Debug /p:AndroidSigningKeyStoreMyKey.keystore /p:AndroidSigningKeyAliasMyAlias # iOS 真机macOS 主机上执行需提前在 Xcode 中配置好 Team 和 Signing Certificate dotnet build -t:Run -f net8.0-ios -c Debug /p:EnableDefaultCompileItemsfalse # Windows需 Windows 10 22H2且开启“开发者模式” dotnet build -t:Run -f net8.0-windows10.0.22621.0 -c Debug逻辑说明-t:Run是 MSBuild 的 Target它隐式触发BuildDeployLaunch/p:参数用于覆盖项目文件中的属性。其中/p:EnableDefaultCompileItemsfalse是 iOS 部署的关键开关——它禁用 MAUI 默认的资源编译规则强制使用 Xcode 的原生构建流程避免mtouch工具链冲突。参数说明AndroidSigningKeyStore必须是 JKS 格式密钥库非 PKCS12。若你只有.p12文件用keytool -importkeystore -srckeystore mykey.p12 -destkeystore mykey.keystore -deststoretype JKS转换。AndroidSigningKeyAlias密钥库中 key 的别名创建密钥库时指定。-c DebugDebug 模式启用热重载和符号调试Release 模式需额外配置签名和优化选项。3. 从 Xamarin.Forms 迁移三步剥离旧架构保留业务逻辑不动摇3.1 项目结构映射XAML 文件不用改但命名空间和初始化必须重写Xamarin.Forms 项目中App.xaml.cs继承ApplicationMainPage.xaml是ContentPageMAUI 中它们分别对应App.xaml无 cs 后缀和MainPage.xaml但基类变为Application和ContentPage的 MAUI 实现。迁移不是重写而是“重绑定”删除所有using Xamarin.Forms;和using Xamarin.Essentials;替换为using Microsoft.Maui;和using Microsoft.Maui.Controls;注意Essentials功能已内建无需单独引用。重写App.xaml的根元素Xamarin.Forms 写法Application xmlnshttp://xamarin.com/schemas/2014/forms Application.MainPage local:MainPage / /Application.MainPage /ApplicationMAUI 写法App.xaml变为纯资源字典导航由MauiProgram.cs控制Application xmlnshttp://schemas.microsoft.com/dotnet/2021/maui Application.Resources ResourceDictionary !-- 全局样式放这里 -- /ResourceDictionary /Application.Resources /ApplicationMauiProgram.cs是新入口替代MainActivity.cs和AppDelegate.cs此文件由 CLI 自动生成核心是ConfigureFonts和ConfigureEffects。业务页面注册在此处public static class MauiProgram { public static MauiApp CreateMauiApp() { var builder MauiApp.CreateBuilder(); builder .UseMauiAppApp() .ConfigureFonts(fonts { fonts.AddFont(OpenSans-Regular.ttf, OpenSansRegular); }); // 关键注册你的页面否则 Shell 找不到 builder.Services.AddSingletonMainPage(); // ← 替换为你自己的 MainPage 类名 return builder.Build(); } }3.2 Shell 导航迁移解决 Android 返回栈混乱与 macOS 菜单栏缺失问题Xamarin.Forms 的Shell在 MAUI 中行为更严格。常见问题Android 按返回键直接退出、macOS 顶部菜单栏空白。根源在于路由注册方式和生命周期钩子。正确做法所有页面必须通过Routing.RegisterRoute显式注册不能只靠 XAML 中的Route属性AppShell.xaml中的FlyoutItem必须绑定到已注册的路由而非直接写ContentPage类型。!-- AppShell.xaml -- FlyoutItem Title首页 Iconicon_home.png ShellContent Routemain ContentTemplate{DataTemplate local:MainPage} / /FlyoutItem对应 C# 注册在MauiProgram.cs的CreateMauiApp方法末尾添加builder.Services.AddSingletonMainPage(); // 必须在 Build() 之前调用 builder.Services.AddMauiBlazorWebView(); // 注册路由关键 Routing.RegisterRoute(main, typeof(MainPage));注意RegisterRoute的第一个参数是字符串路由名如main第二个参数是Type。若此处写错类型Android 返回栈会丢失上下文按返回键直接退到桌面。3.3 自定义渲染器Custom Renderer的替代方案用 MAUI 的Handler机制重写这是迁移中最耗时的部分。MAUI 废弃了ViewRendererTView, TNativeView改用IViewHandler接口和Mapper映射表。以自定义Entry的边框颜色为例Xamarin.Forms 写法Androidpublic class CustomEntryRenderer : EntryRenderer { protected override void OnElementChanged(ElementChangedEventArgsEntry e) { base.OnElementChanged(e); if (Control ! null) Control.SetBackgroundColor(Android.Graphics.Color.ParseColor(#FFEEEEEE)); } }MAUI 写法Android// 在 Platforms/Android/Handlers/CustomEntryHandler.cs public class CustomEntryHandler : EntryHandler { public static IPropertyMapperIEntry, EntryHandler CustomMapper new PropertyMapperIEntry, EntryHandler(EntryHandler.Mapper) { [nameof(IEntry.BackgroundColor)] MapBackgroundColor }; public CustomEntryHandler() : base(CustomMapper) { } static void MapBackgroundColor(IEntryHandler handler, IEntry view) { if (handler.PlatformView is Android.Widget.EditText editText) { editText.SetBackgroundColor(Android.Graphics.Color.ParseColor(#FFEEEEEE)); } } }然后在MauiProgram.cs中替换默认 Handlerbuilder.ConfigureMauiHandlers(handlers { handlers.AddHandler(typeof(Entry), typeof(CustomEntryHandler)); });逻辑说明PropertyMapper是 MAUI 的核心抽象它把 C# 层属性变更映射到原生控件操作。EntryHandler.Mapper是基础映射表我们用new PropertyMapper继承它并重写BackgroundColor的映射逻辑。这种方式比 Renderer 更轻量且天然支持热重载。4. MAUI 开发避坑指南5 个血泪经验总结专治“明明代码一样却跑不通”4.1 现象热重载Hot Reload在 Windows 上完全失效修改 XAML 后无任何反应原因Windows 平台默认禁用热重载的 XAML 支持且 VS 2022 的热重载设置与 MAUI 项目类型强耦合。解决在 Visual Studio 中Tools → Options → Projects and Solutions → .NET Core → Hot Reload勾选Enable Hot Reload for .NET MAUI apps在项目根目录创建Directory.Build.props强制启用Project PropertyGroup EnableDefaultHotReloadfalse/EnableDefaultHotReload EnableHotReloadtrue/EnableHotReload /PropertyGroup /Project启动时必须用dotnet watch而非 VS 的“开始调试”dotnet watch --project MyMauiApp.csproj run -f net8.0-windows10.0.22621.04.2 现象CollectionView在 Windows 上无法垂直滚动内容被截断原因MAUI 8.0 中CollectionView的ItemsLayout默认为VerticalList但在 Windows 上需显式设置HeightRequest或嵌套在ScrollView中否则布局引擎计算高度为 0。解决方案一推荐给CollectionView设置固定高度或VerticalOptionsFillAndExpandCollectionView ItemsSource{Binding Items} VerticalOptionsFillAndExpand CollectionView.ItemTemplate DataTemplate Label Text{Binding Name} / /DataTemplate /CollectionView.ItemTemplate /CollectionView方案二包裹在ScrollView中仅当需复杂嵌套时ScrollView CollectionView ItemsSource{Binding Items} / /ScrollView4.3 现象iOS 真机部署时报错Failed to codesign bundle但 Xcode 中签名正常原因MAUI 构建流程会调用codesign命令但它读取的是Entitlements.plist文件中的application-identifier而该文件未随项目生成或 Bundle ID 与 Apple Developer Account 不匹配。解决在Platforms/iOS/Entitlements.plist中手动添加?xml version1.0 encodingUTF-8? !DOCTYPE plist PUBLIC -//Apple//DTD PLIST 1.0//EN http://www.apple.com/DTDs/PropertyList-1.0.dtd plist version1.0 dict keyapplication-identifier/key stringTEAMID.com.yourcompany.yourapp/string keykeychain-access-groups/key array stringTEAMID.com.yourcompany.yourapp/string /array /dict /plist在MyMauiApp.csproj中指定 Entitlements 文件PropertyGroup Condition$([System.Runtime.InteropServices.RuntimeInformation]::IsOSPlatform($([System.Runtime.InteropServices.OSPlatform]::OSX))) CodesignKeyiPhone Developer/CodesignKey CodesignProvisionyour-provisioning-profile-name/CodesignProvision CodesignEntitlementsPlatforms/iOS/Entitlements.plist/CodesignEntitlements /PropertyGroup4.4 现象Android 启动白屏超过 3 秒Logcat 显示Application did not start in 3000ms原因MAUI 启动时需加载 .NET 运行时和 AOT 编译模块若AndroidManifest.xml中android:theme指向一个含windowBackground的主题而该背景图过大或格式不兼容如 WebP会导致启动卡顿。解决在Platforms/Android/Resources/values/styles.xml中定义极简启动主题style nameMaui.SplashTheme parentTheme.AppCompat.Light.NoActionBar item nameandroid:windowBackgroundcolor/splash_background/item item nameandroid:windowNoTitletrue/item item nameandroid:windowFullscreentrue/item /style在Platforms/Android/Resources/values/colors.xml中定义纯色背景color namesplash_background#FFFFFFFF/color在Platforms/Android/AndroidManifest.xml的application标签中指定android:themestyle/Maui.SplashTheme4.5 现象macOS 上WebView加载网页时崩溃报EXC_BAD_ACCESS (code1, address0x0)原因macOS Catalyst 的WKWebView需要明确启用 JavaScript 和 DOM 访问权限而 MAUI 默认未开启。解决在Platforms/MacCatalyst/Program.cs中在Main方法内UIApplication.Main调用前插入// 启用 WKWebView 的 JS 执行权限 var config new WKWebViewConfiguration(); config.UserContentController new WKUserContentController(); config.Preferences.JavaScriptEnabled true; config.Preferences.JavaScriptCanOpenWindowsAutomatically true; // 将配置传入 WebView 初始化需在 WebView 创建时注入 // 若你使用的是 MAUI 内置 WebView需在 XAML 中设置 Source 后用 Handler 注入 // ((WebViewHandler)webView.Handler).PlatformView.Configuration config;更稳妥的做法是自定义WebViewHandler在MapSource时注入配置类似 3.3 节的CustomEntryHandler。5. 性能调优与发布准备让 MAUI 应用从“能跑”变成“敢上线”5.1 AOT 编译为什么 Release 模式下 Android APK 体积暴增 30MB如何精准裁剪MAUI 的 AOTAhead-of-Time编译是双刃剑它提升启动速度但默认会打包整个 .NET 运行时。一个未裁剪的 Android Release APK 常达 45MB远超 Google Play 的 150MB 推荐上限。裁剪策略分三级裁剪级别操作效果风险L1SDK 无关裁剪在.csproj中添加PublishTrimmedtrue/PublishTrimmed减少约 8–12MB移除未引用的程序集可能因反射调用失败如 JSON 序列化L2Runtime 依赖裁剪添加TrimmerRootAssembly IncludeSystem.Text.Json /针对性保留反射所需程序集避免 L1 的误删需逐个添加用到的反射库L3Native AOT.NET 8PublishAottrue/PublishAotIlcInvariantGlobalizationfalse/IlcInvariantGlobalization体积降至 18–22MB启动快 3x但失去动态代码生成能力不支持System.Reflection.Emit、Regex.CompileToAssembly实操命令Android Releasedotnet publish -f net8.0-android -c Release -p:PublishTrimmedtrue -p:TrimmerRootAssemblySystem.Text.Json -p:TrimmerRootAssemblyMicrosoft.Maui.Controls -p:AndroidPackageFormataab -p:AndroidSigningKeyStoreprod.keystore -p:AndroidSigningKeyAliasprod -p:AndroidSigningKeyPassyourpass -p:AndroidSigningKeyStorePassyourpass逻辑说明-p:AndroidPackageFormataab输出 Android App BundleGoogle Play 强制要求它比 APK 小 15–20%且支持动态交付。TrimmerRootAssembly列表必须包含所有你代码中用到反射的程序集——最安全的做法是先用 L1 发布运行时捕获MissingMethodException再把报错的程序集名加到列表中。5.2 Windows 桌面发布从 ClickOnce 到 MSIX为什么 MSIX 是唯一选择Windows 平台的 MAUI 应用若用传统 ClickOnce会遇到权限弹窗频繁、更新失败率高、无法访问现代 API如 WinUI 3等问题。MSIX 是微软官方推荐的现代打包格式它提供沙盒隔离、后台自动更新、UWP/WinUI 兼容性。生成 MSIX 的最小步骤在MyMauiApp.csproj中启用 MSIXPropertyGroup TargetFrameworknet8.0-windows10.0.22621.0/TargetFramework OutputTypeWinExe/OutputType PublishProfilewin10-msix/PublishProfile UseWPFtrue/UseWPF /PropertyGroup创建Directory.Build.targets注入 MSIX 构建任务Project Target NameGenerateMsix AfterTargetsPublish Exec Commandmakeappx pack /d quot;$(PublishDir)quot; /p quot;$(PublishDir)MyMauiApp.msixquot; / /Target /Project发布命令dotnet publish -f net8.0-windows10.0.22621.0 -c Release -r win-x64 /p:PublishProfilewin10-msix提示MSIX 包签名是上架 Microsoft Store 的硬性要求。本地测试可用自签名证书但 Store 提交必须用 DigiCert 或 Sectigo 的 EV 代码签名证书。签名命令SignTool sign /fd SHA256 /a /tr http://timestamp.digicert.com /td SHA256 /v MyMauiApp.msix5.3 iOS 发布终极 checklist从 Archive 到 App Store Connect 的 7 个必验点MAUI iOS 发布不是“Build → Archive → Upload”而是 7 个环环相扣的验证点漏一个就会被 App Store Connect 拒绝序号检查项验证方法失败后果1Bundle ID 一致性Info.plist中CFBundleIdentifier必须与 Apple Developer Portal 中 App ID 完全一致含大小写Archive 失败报No matching provisioning profiles found2Provisioning Profile 类型必须为App Store类型非Development或Ad Hoc上传后被 App Store Connect 拒收提示Invalid Provisioning Profile3Privacy DescriptionsInfo.plist中必须包含NSCameraUsageDescription、NSPhotoLibraryUsageDescription等即使未用也要占位审核被拒理由Missing Info.plist key4App Icons 尺寸Resources/AppIcon/appicon.svg必须导出为1024x1024.png且Assets.xcassets中所有尺寸图标存在上传成功但审核失败提示Invalid Binary5Bitcode 禁用在MyMauiApp.csproj中添加MtouchEnableBitcodefalse/MtouchEnableBitcodeXcode 15 默认禁用 Bitcode但 MAUI 项目需显式关闭6WatchKit 支持若项目含 Watch AppInfo.plist中WKCompanionAppBundleIdentifier必须指向主 App Bundle IDWatch App 无法安装主 App 无法通信7App Store Connect 元数据Marketing URL、Support URL、Privacy Policy URL必须为 HTTPS 且可公开访问提交后卡在Processing状态超 24 小时验证脚本macOS 终端运行# 检查 Info.plist 关键字段 plutil -p Platforms/iOS/Info.plist | grep -E (CFBundleIdentifier|NS.*UsageDescription) # 检查图标是否存在且尺寸正确 sips -g pixelWidth -g pixelHeight Resources/AppIcon/appicon.svg 2/dev/null | grep -E (1024|1024) # 检查 .csproj 中 Bitcode 设置 grep -n MtouchEnableBitcode MyMauiApp.csproj我做过的最痛一次发布是在第 3 步漏了NSLocationWhenInUseUsageDescription结果 App Store 审核花了 7 天——因为团队以为是功能 bug反复修改代码重提直到第 5 次被拒才意识到是隐私描述缺失。从此我的发布 checklist 第一条就是打开Info.plist逐行对照苹果文档里的 Required Keys 。希望帮到你。本文还有配套的精品资源点击获取
