如何使用Idea与Gradle调试Kotlin Symbol Processing (KSP)

适用版本 #

Kotlin 1.5.31 + KSP 1.5.31-1.0.0

操作步骤 #

• 首先终止所有存量Gradle守护进程，避免进程干扰：

  ./gradlew --stop
  

• 运行带调试参数的构建命令，替换<target-task>为你实际要执行的构建任务（比如assembleDebug）：

  ./gradlew <target-task> \
    -Dorg.gradle.jvmargs="-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005" \
    -Pkotlin.compiler.execution.strategy="in-process" \
    --no-parallel
  

  参数说明：
  • agentlib:jdwp=...：开启JVM调试服务，监听5005端口，suspend=y表示进程启动后立即暂停，等待调试器附加后再继续执行
  • kotlin.compiler.execution.strategy="in-process"：强制Kotlin编译器（含KSP执行逻辑）运行在Gradle主进程内，避免额外启动独立Worker进程导致无法命中断点
  • --no-parallel：关闭并行构建，避免多任务并发执行干扰调试流程
• 命令执行后会输出Listening for transport dt_socket at address: 5005，此时打开IDE，新建Remote JVM Debug配置，端口填写5005，点击调试按钮附加进程即可。附加成功后构建流程会自动继续，你在KSP处理器中打的断点会正常命中。

常见问题排查 #

• 如果提示5005端口被占用，可修改address后的端口值为任意空闲端口，IDE的远程调试配置端口也要对应修改
• 断点无法命中时，检查KSP模块的编译配置是否开启了调试信息生成，未开启混淆

内容的提问来源于stack exchange，提问作者Max Farsikov