Compose Multiplatform 项目中 Android 平台资源加载问题解析

问题背景

在 Compose Multiplatform 项目中，开发者 GuilhE 遇到了一个关于 Android 平台资源加载的特殊问题。当项目在 Android 平台上运行时，系统抛出 org.jetbrains.compose.resources.MissingResourceException 异常，提示无法找到 XML 格式的矢量图资源（如 drawable/ic_logo.xml），而 PNG 和 OTF 格式的资源却能正常加载。

项目结构分析

该问题出现在一个多模块的 Compose Multiplatform 项目中，其结构特点如下：

1. 共享UI模块（shared-ui/commonMain/composeResources）：存放了所有共享资源，包括 PNG、XML 矢量图和 OTF 字体文件
2. 桌面应用模块（desktopApp）：导入 shared-ui 模块并正常使用其组件和资源
3. WASM/JS 目标模块（wasmJsMain）：位于 shared-ui 模块内，资源使用正常
4. Android 目标模块（androidMain）：同样位于 shared-ui 模块内，但 XML 资源加载失败

问题根源

经过深入排查，发现问题根源在于项目的 Gradle 构建配置中。开发者在 packaging.resources 配置中显式排除了所有 XML 文件：

packaging {
    resources {
        excludes.addAll(
            listOf(
                "**/*.xml",  // 这行配置导致问题
                // 其他排除规则...
            )
        )
    }
}

这一配置原本是为了优化 APK 大小，移除清单文件和 APK 中的多余文件。然而，它意外地影响了 Compose Multiplatform 的资源加载机制。

技术原理

在 Compose Multiplatform 中，资源加载机制在不同平台上有不同实现：

1. Android 平台：使用 Java 类加载器机制加载资源

   • 对于 PNG 等二进制资源，能正常通过 classLoader.getResourceAsStream() 获取
   • 对于 XML 资源，由于打包配置的排除规则，导致资源流为 null

2. 其他平台：使用不同的资源加载策略，不受此配置影响

值得注意的是，Android 原生资源（位于 androidMain/res 目录）不受此配置影响，因为它们是作为 Android 资源而非 Java 资源处理的。

解决方案

针对这一问题，开发者可以采取以下解决方案：

1. 修改打包配置：移除对 XML 文件的全局排除规则，或针对 Compose 资源目录设置更精确的排除规则

2. 资源分类处理：

   • 将 Android 原生资源（XML 矢量图等）放在 androidMain/res 目录
   • 将跨平台共享资源放在 commonMain/composeResources 目录
   • 针对不同资源类型设置不同的打包规则

3. 资源加载优化：对于必须排除的 XML 文件，考虑转换为其他格式或实现自定义资源加载逻辑

经验总结

这个案例为我们提供了几个重要的经验教训：

1. 多平台资源管理：在跨平台项目中，需要明确区分平台特定资源和共享资源的管理方式

2. 构建配置影响：打包配置会直接影响运行时行为，需要谨慎设置排除规则

3. 问题排查方法：当资源加载出现问题时，应该：

   • 检查资源文件是否实际被打包到最终产物中
   • 验证不同资源类型的加载行为差异
   • 对比工作项目和非工作项目的配置差异

4. Compose Multiplatform 资源机制：目前版本中，资源功能在单模块项目中工作最佳，多模块项目可能需要额外配置

通过这个案例，开发者可以更好地理解 Compose Multiplatform 在 Android 平台上的资源加载机制，并在未来项目中避免类似的配置问题。