.NET Android 9.0 中 Kotlin 标准库打包问题的分析与解决

问题背景

在将 .NET Android 应用从 .NET 6.0 迁移到 .NET 9.0 的过程中，开发人员遇到了一个关于 Kotlin 标准库打包的严重问题。应用使用了 Kotlin 绑定功能，需要依赖 Kotlin.StdLib 和 Kotlin.Reflect 包，但在 .NET 9.0 环境下，无论是 DEBUG 还是 RELEASE 模式，应用都无法正常运行。

问题现象

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

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 文件中排除。这个问题在 .NET 8.0 中可以通过修改项目配置解决，但在 .NET 9.0 中又出现了新的变化。

技术分析

打包排除机制的变化

在 .NET 9.0 中，Android 打包系统对 Kotlin 相关文件有以下默认排除规则：

• 排除所有匹配 *.kotlin* 模式的文件
• 排除 DebugProbesKt.bin 文件

这些规则定义在 SDK 的 AutoImport.props 文件中，通过 AndroidPackagingOptionsExclude 和 AndroidPackagingOptionsInclude 两个 MSBuild 项来控制。

配置覆盖的问题

在 .NET 8.0 中，开发人员可以通过在项目文件中添加以下配置来覆盖默认排除规则：

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

但在 .NET 9.0 中，这种方法失效了，原因在于：

1. 打包排除规则的加载顺序发生了变化
2. 在 Debug 构建模式下存在一个已知的 bug，导致包含规则没有被正确应用

解决方案

正确的配置方式

对于 .NET 9.0 项目，正确的配置方法如下：

1. 创建一个单独的 props 文件（如 KotlinPackaging.props），内容如下：

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

2. 在项目文件中导入这个 props 文件：

<Project Sdk="Microsoft.NET.Sdk">
    <!-- 其他配置 -->
    <Import Project="KotlinPackaging.props" />
</Project>

注意事项

1. 不要使用 Directory.Build.props：因为它在构建过程中加载过早，无法正确覆盖 SDK 的默认设置。

2. Debug 构建的特殊处理：目前 Debug 构建模式下存在一个 bug，可能需要等待官方修复或临时修改 SDK 的 AutoImport.props 文件。

3. .NET 版本兼容性：如果项目目标是 net8.0-android，即使使用 .NET 9.0 SDK，也会使用 .NET 8.0 的构建目标和规则。

技术原理深入

Android 打包系统的工作机制

.NET Android 的打包系统基于 MSBuild 任务实现，它会扫描所有依赖的 Java 库（包括绑定的 Kotlin 库），并根据打包规则决定哪些文件应该包含在最终的 APK 中。

打包规则通过正则表达式匹配文件路径，AndroidPackagingOptionsExclude 定义了要排除的模式，而 AndroidPackagingOptionsInclude 则可以覆盖排除规则。

构建顺序的重要性

在 MSBuild 中，项的修改是顺序敏感的。要覆盖 SDK 的默认设置，必须在 SDK 导入其默认值之后进行修改。这就是为什么在 .NET 9.0 中，将覆盖规则放在单独导入的文件中比放在 Directory.Build.props 中更有效。

最佳实践建议

1. 明确声明依赖：确保项目中正确声明了对 Kotlin 标准库的依赖：

<ItemGroup>
    <PackageReference Include="Xamarin.Kotlin.StdLib" Version="2.0.21.1" />
</ItemGroup>

2. 构建日志分析：在遇到打包问题时，检查构建日志中 AndroidPackagingOptionsExclude 和 AndroidPackagingOptionsInclude 的最终值，确认自定义规则是否生效。

3. APK 内容验证：使用工具检查生成的 APK 文件，确认 Kotlin 相关文件是否被正确包含。

总结

.NET Android 9.0 对打包系统进行了改进，但也带来了 Kotlin 库打包的新挑战。通过理解 MSBuild 的构建顺序和打包规则的工作机制，开发人员可以正确配置项目以确保 Kotlin 标准库被包含在最终的 APK 中。随着 .NET Android 的持续发展，建议关注官方更新以获取更优雅的解决方案。