.NET Maui iOS调试报错：无法加载Xamarin.HotReload.Contracts.dll

问题复现 #

应用在Android设备调试/部署正常，iOS设备可正常部署运行，但仅iOS调试时启动失败，核心报错信息：

System.IO.FileNotFoundException: Could not load file or assembly '/var/mobile/.../Xamarin.HotReload.Contracts.dll' or one of its dependencies.

解决方案 #

• 临时禁用Hot Reload调试

  1. 打开Visual Studio顶部菜单栏「调试」→「选项」→「调试」→「.NET Hot Reload」
  2. 取消勾选「启用.NET Hot Reload」，保存后重新启动调试
     或者直接点击调试按钮旁的下拉箭头，选择「禁用Hot Reload启动」

• 清理重建项目

  • 右键解决方案 →「清理解决方案」
  • 右键iOS项目 →「卸载项目」，完成后再右键选择「重新加载项目」
  • 重新生成解决方案后尝试调试

• 检查项目引用
  确认iOS项目中没有手动添加Xamarin.HotReload.Contracts或Microsoft.VisualStudio.DesignTools.TapContract的引用，这类调试专属程序集由Visual Studio自动管理，手动添加会导致部署时无法正确同步到设备。

原因说明 #

该问题源于Visual Studio的.NET Hot Reload组件在iOS调试场景下，未能自动将依赖的调试合约程序集部署到目标设备。iOS调试模式需要加载这些组件实现热重载交互，但部署过程中遗漏了相关文件，导致启动时触发文件未找到异常；而正常部署运行时无需加载调试组件，因此能正常启动。

内容的提问来源于stack exchange，提问作者Cloud-Lover