返回

解决 MAUI .NET 8 升级 Xcode 16 兼容性问题

IOS

MAUI 项目 .NET 8 升级及 Xcode 16 兼容性问题

在将混合型 MAUI 项目从 .NET 7 升级到 .NET 8 的过程中,同时伴随 macOS 更新和 Xcode 升级至 16 版本,部分开发者可能会遇到构建错误。特别地,iOS 构建过程中出现的 ArgumentNullException: Value cannot be null. Parameter name: path2 错误,指向 Xamarin.Shared.targets 文件 643 行,这是值得关注的问题。此类问题阻碍了 iOS 模拟器运行和真机调试,也使得应用发布受阻。

问题根源分析

此异常的核心是 path2 参数为空。该参数在构建流程中通常与资源文件路径或配置文件路径有关。 当项目更新框架或 Xcode 版本后,一些构建过程相关的配置路径或依赖关系可能会发生变化,导致构建工具找不到需要的资源文件,最终导致参数为空。具体原因可能包含以下几点:

  1. 配置不匹配 : 升级过程可能导致 MAUI 项目配置、依赖关系与 Xcode 16 的新要求不完全匹配。
  2. 缓存或中间文件干扰 : 残留的旧版本缓存文件,或之前构建生成的中间文件可能与新的 .NET 8 环境冲突,引发构建错误。
  3. 项目结构问题 : 复杂的项目结构,如共享库、WebAssembly 引用等,可能导致路径解析问题,特别是在 MAUI 应用和 Xamarin/MAUI SDK 不同之处。
  4. 签名问题 : Xcode 更新后,证书配置的差异也可能间接导致路径识别的问题。
  5. .NET SDK 冲突 : 不同版本的 .NET SDK 冲突也有可能影响构建过程中的路径处理。

解决方案

针对上述可能原因,提供如下解决方案:

1. 清理和重建项目

最常见的解决方案是执行清理和重建操作,消除缓存和旧中间文件带来的影响。

  • Visual Studio: 在 Visual Studio 中右键单击解决方案,选择 “清理解决方案”,然后选择 “重新生成解决方案”。
  • 命令行: 使用 dotnet CLI:
    dotnet clean
    dotnet build
    

清理操作清除 binobj 目录,确保构建过程从干净的状态开始。
重新生成操作编译代码,创建应用。

2. 验证 Info.plist 文件路径

确保 Info.plist 文件的路径配置正确,并且内容有效。检查 项目属性iOS 构建部分配置。

  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|iPhoneSimulator' ">
     ...
   <BundleIdentifier>$(ApplicationId)</BundleIdentifier>
    <CodesignKey>Apple Development: xxx (xxxx)</CodesignKey>
      <CodesignProvision>xxx-xxx-xxx-xxx</CodesignProvision>
     <ProvisioningType>manual</ProvisioningType>
  ...
</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|iPhone' ">
 ...
    <CodesignKey>Apple Distribution: xxx (xxxx)</CodesignKey>
  <CodesignProvision>xxx-xxx-xxx-xxx</CodesignProvision>
    <ProvisioningType>manual</ProvisioningType>
...
</PropertyGroup>

尤其要核查 “应用标识符”,“代码签名”和 “Provisioning 文件” 这些配置的路径正确,这些配置的缺失或错误都可能导致构建过程中资源路径问题。

3. 更新 MAUI 项目的 SDK

检查 .csproj 文件中,确保 MAUI 相关 NuGet 包以及相关插件的版本都是最新的。例如:

<PackageReference Include="Microsoft.Maui.Controls" Version="[8.0.0,9.0.0)" />
<PackageReference Include="Microsoft.Maui.Essentials" Version="[8.0.0,9.0.0)" />
  <!-- ... 其他依赖 ...-->

使用版本范围来指定兼容的包版本。推荐安装官方发布包。如果升级后还不能解决问题,可以先尝试把所有 nuget 包版本回退到先前可用的版本,来判断问题是不是由版本更新造成。

4. 核查签名配置和Xcode配置

检查Xcode中是否有重复或冲突的配置文件,及时清理多余文件。并在 MAUI 项目设置中确保签名信息(签名密钥和配置文件)与 Xcode 中配置匹配。如有不一致,需要在开发人员中心更新密钥对,并将 Xcode 中的相关设置同步。

  1. 打开 Xcode,在 Settings->Accounts 中确保添加了苹果开发者账户

  2. 进入 Targets 配置界面,在 Signing & Capabilities中更新配置文件

    确认以下配置正确:

    • Team: 选择正确的开发者账号
    • Signing Certificate: 选择证书
    • Provisioning Profile: 选择配置文件, 或者选择 Automatically manage signing 自动管理。

5. 隔离构建测试

创建一个最简 MAUI 应用,确认在同样环境可以正常构建和运行,以便快速排查是 MAUI 环境的问题还是代码引入的问题。 使用 dotnet new maui -n MinimalApp创建新的最小化应用,进行初步排错。如果最小化项目正常,问题可能出在你的主应用结构和依赖上面,可以进一步深入排查。

安全建议

  • 定期备份 : 在每次大版本升级前,建议对项目进行完全备份,以防升级过程出现问题可以及时回滚。
  • 小步迭代 : 不要一次性更新多个组件或依赖项。最好分步骤进行,每次更新后都要进行测试。
  • 持续集成 : 在持续集成环境中测试,及时发现问题。这样避免问题积累过多后,导致难以解决的状况发生。
  • 细读文档 : 及时关注 .NET 和 Xcode 的发布说明。特别是升级版本后的变更日志,有助于规避一些已知的问题。

遇到 “ArgumentNullException” 这样的错误时,应仔细排查,从配置,依赖,到构建环节逐个验证。 遵循小步快跑,持续迭代的方法,能有效降低升级带来的风险。通过这些建议和方案,大多数类似问题可以得到有效解决,并确保项目的平稳过渡。