Compose Multiplatform 项目中自定义资源目录结构的挑战与解决方案

背景介绍

在 Kotlin Multiplatform (KMP) 项目开发中，Compose Multiplatform 提供了便捷的资源管理机制，允许开发者通过类型安全的访问器（如 Res.drawable.cupcake）引用资源。然而，当开发者尝试自定义项目目录结构时（例如减少目录嵌套层级），这一机制可能会失效，导致必须回退到原始的 DrawableResource("drawable/cupcake.xml") 方式访问资源。

问题现象

典型场景发生在 Gradle 配置中修改了默认的资源路径。例如：

sourceSets {
    val commonMain by getting {
        kotlin.apply {
            srcDir("commonMain") // 自定义源码目录
            resources.srcDir("commonMain/composeResources") // 自定义资源目录
        }
    }
}

此时，Compose 的资源访问器无法自动生成，而将路径恢复为包含 src 的标准结构（如 src/commonMain/composeResources）则问题消失。

技术根源

Compose Multiplatform 的资源处理插件在生成访问器时，默认依赖以下约定：

1. 资源目录必须位于 src/[sourceSetName]/composeResources 的层级结构中
2. 插件通过预定义的路径模式扫描资源文件并生成对应 Kotlin 代码

当目录结构脱离此约定时，插件的资源发现逻辑会失效。这本质上是因为路径解析逻辑未考虑完全自定义的目录布局。

实际影响

1. 开发体验降级：被迫使用字符串硬编码路径，失去类型安全和 IDE 自动补全
2. 项目结构限制：无法实现扁平化目录等现代项目组织方式
3. 构建系统兼容性问题：如 Amper 等新兴构建工具的原生布局支持受阻

解决方案与变通方法

临时方案

保持 src 前缀的目录结构，这是当前最稳定的兼容性方案：

resources.srcDir("src/commonMain/composeResources") 

长期建议

对于插件开发者，可考虑以下增强方向：

1. 支持通过 Gradle 扩展显式指定资源目录
2. 实现更灵活的资源扫描策略，允许正则匹配或通配符配置
3. 提供资源根目录的显式声明选项

最佳实践建议

1. 混合目录结构：对 Compose 资源保持标准路径，其他自定义内容放在平行目录
2. 构建脚本抽象：通过变量管理路径，便于全局调整

val composeResDir = "customPath/composeResources"
resources.srcDir(composeResDir)

未来展望

随着 KMP 生态的成熟，资源管理将需要更灵活的配置方案。JetBrains 团队已注意到相关需求（如对 Amper 构建工具的支持），预计未来版本会引入更动态的路径解析机制。开发者可关注插件的资源处理模块更新，及时适配新特性。

对于需要立即使用自定义目录的团队，建议通过编写自定义 Gradle 任务生成资源访问器作为过渡方案，但这需要维护额外的构建逻辑。