Compose Multiplatform 中构建包含 UI 和资源的 XCFramework 指南

在 Kotlin Multiplatform (KMP) 生态中，Compose Multiplatform 为开发者提供了跨平台 UI 开发的强大能力。然而，当需要将包含 Compose UI 的代码打包为 iOS 可用的 XCFramework 时，开发者往往会遇到一些特有的挑战。

核心挑战

与纯 Kotlin 代码不同，Compose Multiplatform 框架打包面临两个主要技术难点：

1. 资源文件处理：iOS 生态缺乏统一的资源分发规范，不同包管理器（如 CocoaPods 和 SPM）有各自的资源处理方式
2. UI 组件集成：Compose 的 UI 组件需要正确打包并与原生 iOS 视图系统协同工作

解决方案详解

1. 基础框架构建

构建包含 Compose 的 XCFramework 与构建普通 Kotlin 框架流程基本一致。关键在于正确处理资源文件和 UI 依赖。

2. 资源文件处理策略

对于 CocoaPods 使用者：

• 使用 syncFramework Gradle 任务生成资源目录
• 资源文件默认输出路径为 build/compose/cocoapods/compose-resources
• 需要在 podspec 文件中显式声明资源目录

3. 多平台配置建议

在项目的 build.gradle.kts 中，建议配置如下：

kotlin {
    iosX64()
    iosArm64()
    iosSimulatorArm64()
    
    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation(compose.runtime)
                implementation(compose.foundation)
                implementation(compose.material)
            }
        }
    }
}

4. 框架打包优化

为获得最佳兼容性，建议：

• 包含所有 iOS 架构（arm64, x86_64, simulator）
• 明确声明资源文件依赖
• 测试在不同包管理器下的资源加载行为

最佳实践

1. 资源管理：将图片、字体等资源统一放在 commonMain/resources 目录
2. 版本控制：确保 Compose Multiplatform 版本与 Kotlin 版本兼容
3. 测试验证：在真机和模拟器上全面测试框架功能
4. 依赖管理：使用 api 而非 implementation 暴露必要的 Compose 依赖

常见问题排查

若遇到资源加载失败：

• 检查资源是否被正确打包到最终框架中
• 验证 podspec 或 Package.swift 中的资源路径配置
• 确保资源文件没有被意外优化掉

通过遵循这些指导原则，开发者可以成功构建包含 Compose UI 的 XCFramework，并在 iOS 生态系统中无缝分发和使用。