Kotlinx.serialization在KMP项目中的正确配置指南

在使用Kotlin Multiplatform（KMP）开发时，kotlinx.serialization是一个常用的序列化库。本文将详细介绍如何正确配置该库以避免常见的编译问题。

常见配置误区

许多开发者按照官方文档配置后，仍然会遇到"kotlinx.serialization compiler plugin is not applied to the module"的警告。这通常是因为只添加了插件依赖但没有在具体模块中应用插件。

完整配置步骤

1. 版本管理配置（推荐使用libs.versions.toml）

在版本管理文件中添加以下内容：

[versions]
kotlin = "2.0.0"
kotlinxSerialization = "2.0.0"

[plugins]
kotlinMultiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
kotlinxSerialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlinxSerialization" }

2. 项目级build.gradle配置

在项目根目录的build.gradle文件中声明插件：

plugins {
    alias(libs.plugins.kotlinMultiplatform) apply false
    alias(libs.plugins.kotlinxSerialization) apply false
}

3. 模块级build.gradle配置

这是关键步骤，必须在需要使用序列化的模块中应用插件：

plugins {
    alias(libs.plugins.kotlinxSerialization)
}

为什么需要这样做？

Kotlin编译器插件（包括序列化插件）需要在实际编译代码的模块中显式应用。仅仅在项目级声明而不应用，会导致编译器无法处理@Serializable等注解。

最佳实践建议

1. 对于多模块项目，只在需要使用序列化的模块中应用插件
2. 确保Kotlin版本与序列化库版本兼容
3. 使用版本管理工具统一管理依赖版本
4. 在应用插件后，记得同步Gradle项目

常见问题排查

如果仍然遇到问题，可以检查：

1. Gradle同步是否成功完成
2. 模块是否正确应用了插件
3. Kotlin版本是否匹配
4. 是否在正确的模块中使用了@Serializable注解

通过以上步骤，开发者可以避免常见的序列化插件配置问题，确保KMP项目中的序列化功能正常工作。