.NET MAUI Debug构建正常，Release构建失败该如何解决？

通用排查步骤 #

• 查看详细构建日志：在Visual Studio的输出窗口，把日志级别切换为详细或诊断，重新运行Release构建，日志中会包含隐藏的具体错误（比如代码分析、AOT编译、资源打包环节的问题）
• 核对项目配置：右键项目→属性，检查Release模式设置：
  • 确认优化代码选项未误删反射类、动态调用的代码，必要时暂时关闭测试
  • 检查AOT编译、LLVM优化是否开启，部分复杂逻辑在AOT编译下会出错，可先关闭尝试构建
  • 确保目标框架与设备/模拟器的系统版本兼容

iOS平台专属排查 #

• 检查签名配置：Release模式必须使用分发证书（不能用开发证书），进入Signing & Capabilities确认证书、Provisioning Profile未过期且配置正确
• 清理iOS构建缓存：删除~/Library/Caches/Xamarin/mtbs和项目目录下的bin/Release、obj/Release文件夹，重新构建
• 校验Info.plist：确认Release模式下的CFBundleIdentifier、CFBundleVersion等字段无特殊字符，格式合法
• 禁用增量构建：在项目.csproj文件中添加<UseIncrementalBuild>false</UseIncrementalBuild>，强制全量构建避免缓存异常

Android平台专属排查 #

• 检查混淆配置：Release模式默认开启R8混淆，若代码包含反射调用、未配置混淆规则的第三方库，会导致构建失败。先在Properties/Android Options中关闭Enable R8测试，若正常则补充对应混淆规则
• 清理Android构建缓存：删除%USERPROFILE%\AppData\Local\Xamarin\zips和项目的bin/Release、obj/Release文件夹
• 核对SDK版本：确认Release模式的目标框架、最小SDK版本与模拟器/设备的系统版本匹配
• 检查资源文件：所有图片、布局等资源的命名不能包含中文或特殊字符，Release打包对资源格式要求更严格

额外测试建议 #

• 尝试命令行构建：打开终端进入项目目录，执行dotnet publish -f net8.0-ios -c Release（iOS）或dotnet publish -f net8.0-android -c Release（Android），命令行输出会比IDE更详细地展示错误信息
• 简化项目排查：暂时移除第三方库、自定义渲染器等复杂组件，逐步还原排查，定位导致Release构建失败的具体模块

内容的提问来源于stack exchange，提问作者SuperT