Kotlin Multiplatform + Compose Multiplatform项目中全局启用ExperimentalMaterial3Api的正确方式

阿华AIGC实验室

2026-4-8

嘿，我完全懂你现在碰到的麻烦——在KMM+CMP项目里想全局开启ExperimentalMaterial3Api的opt-in，结果每个平台都报注解找不到的错误，太闹心了。我来帮你捋清楚正确的配置方式，还有可能踩的坑。

先排查核心问题：重复的Material3依赖

看你的build.gradle.kts配置，commonMain的依赖里同时加了implementation(compose.material3)和implementation(libs.material3)，这大概率是问题根源！

compose.material3是Compose Multiplatform专用的Material3库，包含了跨平台可用的ExperimentalMaterial3Api注解；
而libs.material3如果指向的是Android原生的com.google.android.material:material库，那这个依赖只在Android平台有效，非Android平台（比如iOS）根本找不到这个库，自然会报注解未识别的错误。

第一步：清理重复依赖
把commonMain.dependencies里的implementation(libs.material3)删掉，只保留implementation(compose.material3)就够了。修改后的依赖块示例：

commonMain.dependencies {
    implementation(libs.compottie)
    implementation(compose.runtime)
    implementation(compose.foundation)
    implementation(compose.material3) // 仅保留Compose Multiplatform的Material3库
    implementation(libs.adaptive)
    implementation(compose.materialIconsExtended)
    implementation(compose.ui)
    implementation(libs.kotlinx.serialization.json)
    implementation(libs.navigation.compose)
    implementation(compose.components.resources)
    implementation(compose.components.uiToolingPreview)
    implementation(libs.androidx.lifecycle.viewmodel)
    implementation(libs.androidx.lifecycle.runtimeCompose)
    implementation(project.dependencies.platform(libs.koin.bom))
    implementation(libs.koin.core)
    implementation(libs.koin.compose)
    implementation(libs.koin.compose.viewmodel)
    implementation(libs.koin.compose.viewmodel.navigation)
    api(libs.kotlinx.coroutines.core)
}

两种全局Opt-In的正确配置方式

解决依赖问题后，再配置全局的opt-in，有两种靠谱的方式：

方式一：通过SourceSets全局配置（和你之前的思路一致，确保在kotlin块内）

在kotlin代码块中，针对所有sourceSet统一配置opt-in：

kotlin {
    applyDefaultHierarchyTemplate()
    // ... 你的Android、iOS平台配置
    
    // 全局启用ExperimentalMaterial3Api
    sourceSets.all {
        languageSettings.optIn("androidx.compose.material3.ExperimentalMaterial3Api")
    }

    // ... 你的sourceSets依赖配置
}

方式二：使用Compose插件的Experimental扩展（更简洁，推荐）

Compose Multiplatform插件提供了专门的扩展来配置实验性API的opt-in，写法更清爽：

kotlin {
    applyDefaultHierarchyTemplate()
    // ... 你的平台配置
    
    // 全局启用Material3的实验性API
    compose.experimental {
        optIn("androidx.compose.material3.ExperimentalMaterial3Api")
    }

    // ... 你的sourceSets依赖配置
}