IntelliJ导入kotlinx-serialization-json库后import报错如何解决

kotlinx-serialization 不是普通开箱即用的第三方工具库，强依赖Kotlin官方序列化编译器插件做编译期代码生成。仅手动添加JSON运行时依赖、未配置匹配版本的序列化插件是该类导入报错的核心诱因。你通过Project Structure手动导入Maven构件的操作，仅完成了运行时资源引入，缺失编译器插件配置时，IDE无法完成对应代码符号索引、也无法识别序列化相关语法标记，就会出现外部库列表可见对应jar、代码内import直接飘红的问题。

• 优先确认项目构建方式
  • 若使用Gradle管理项目（Kotlin生态主流选择）：立刻放弃手动在Project Structure中加依赖的操作，手动导入的依赖不会同步编译器插件配置，直接修改构建脚本完成配置即可：
    1. 在根目录构建文件中声明序列化插件，注意插件版本必须和项目使用的Kotlin版本完全一致：kotlinx-serialization-json:1.3.2 对应兼容Kotlin 1.5.0~1.5.31版本，参考配置如下：

       // 以Gradle Kotlin DSL为例
       plugins {
           kotlin("jvm") version "1.5.31"
           kotlin("plugin.serialization") version "1.5.31" // 与上方Kotlin版本号完全相同
       }
       

    2. 在对应模块的依赖配置块中，替换手动导入的依赖，声明正式的序列化JSON依赖：

       dependencies {
           implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.3.2")
       }
       

    3. 点击Gradle面板的刷新按钮等待依赖同步完成，同步结束后执行File -> Invalidate Caches...，勾选清除IDE缓存选项后重启，等待索引重建完成即可。
  • 若使用IntelliJ原生无构建工具项目（手动管理所有依赖）：按以下顺序排查
    1. 打开Settings -> Plugins查看内置Kotlin插件版本，确认版本落在1.5.0~1.5.31区间，版本不匹配时要么升降级Kotlin插件，要么更换对应匹配版本的kotlinx-serialization库。
    2. 回到Project Structure -> Modules，选中你编写代码的对应模块，切换到Dependencies标签页，确认已添加的kotlinx-serialization-json依赖作用域为Compile，如果是Provided/Runtime/Test等其他作用域，直接修改为Compile。
    3. 点开Libraries列表中对应的序列化依赖条目，检查Classes路径下是否存在二进制jar包，如果只有Sources、Javadoc对应的包，删除现有依赖重新从Maven导入，确保二进制jar被正确加载。
    4. 以上操作完成后仍飘红，直接执行清缓存重启操作，等待索引重建完成。
• 配置有效性验证
  写入以下测试代码，无导入飘红、可正常运行即代表配置生效：

  import kotlinx.serialization.Serializable
  import kotlinx.serialization.json.Json
  
  @Serializable
  data class Demo(val id: Int, val content: String)
  
  fun main() {
      val demo = Demo(1, "test")
      println(Json.encodeToString(Demo.serializer(), demo))
  }
  

kotlinx-serialization 与Kotlin编译器版本存在严格的一一对应关系，版本不匹配会直接导致导入失败、编译报错、运行时异常等各类问题，使用前务必确认版本匹配度。原生IDEA手动管理依赖的模式配置序列化插件门槛极高，迁移到Gradle管理项目依赖可规避绝大多数配置问题。

内容的提问来源于stack exchange，提问作者The Computer Genius