Xamarin.Android 中解决 Kotlin 标准库打包问题的技术指南

问题背景

在将 .NET Android 应用从 .NET 6.0 迁移到 .NET 9.0 的过程中，许多开发者遇到了 Kotlin 标准库相关代码被错误排除的问题。这个问题尤其影响那些使用了 Kotlin 绑定的应用，特别是需要 Kotlin.StdLib 和 Kotlin.Reflect 包的应用。

问题表现

当应用运行时，会抛出以下异常：

java.lang.AssertionError: Built-in class kotlin.Any is not found at 
kotlin.reflect.jvm.internal.impl.builtins.KotlinBuiltIns$3.invoke(KotlinBuiltIns.java:93)

根本原因是自 .NET 7.0 起，SDK 默认会将 kotlin 相关代码从最终 APK 文件中排除。

技术分析

打包选项机制

Xamarin.Android 提供了 AndroidPackagingOptionsExclude 和 AndroidPackagingOptionsInclude 两个 MSBuild 项来控制打包过程中包含或排除的文件。这些选项在 .NET 9.0 中被移到了 AutoImport.props 文件中。

排除规则的影响

默认情况下，SDK 会排除以下模式的文件：

• *.kotlin*
• *.kotlin_*
• DebugProbesKt.bin

这些规则会导致 Kotlin 标准库的关键文件被错误排除，从而引发运行时错误。

解决方案

方法一：直接修改项目文件

在项目文件(.csproj)中添加以下内容：

<ItemGroup>
    <AndroidPackagingOptionsExclude Remove="@(AndroidPackagingOptionsExclude)" />
    <AndroidPackagingOptionsInclude Include="$([MSBuild]::Escape('*.kotlin*'))" />
    <AndroidPackagingOptionsInclude Include="$([MSBuild]::Escape('*.kotlin_builtins'))" />
</ItemGroup>

方法二：使用导入文件

1. 创建一个单独的 .props 文件（如 KotlinPackaging.props）
2. 在其中添加上述 ItemGroup 内容
3. 在项目文件中导入：

<Import Project="KotlinPackaging.props" />

注意事项

1. 构建类型差异：在 .NET 9.0 中，Debug 构建存在一个已知问题，可能会导致这些设置不生效。这个问题已在最新版本中修复。

2. SDK版本兼容性：使用 .NET 8.0 目标框架时，即使使用 .NET 9.0 SDK，也会加载 .NET 8.0 的构建目标。

3. 导入时机：确保修改打包选项的代码在 AutoImport.props 之后执行。使用 Directory.Build.props 可能为时过早。

最佳实践建议

1. 对于新项目，建议直接使用 .NET 9.0 目标框架
2. 在团队开发中，将打包配置放入共享的 .props 文件并导入
3. 定期检查构建日志，确认打包选项是否按预期应用
4. 对于关键依赖，考虑在项目中进行显式包含

通过正确配置打包选项，开发者可以确保 Kotlin 相关代码被正确包含在最终 APK 中，从而避免运行时错误。