Gradle多模块Spring Boot项目中自定义BootRun调试任务报ClassNotFoundException的原因及正确配置方法

一、问题原因分析 #

你遇到的ClassNotFoundException主要源于两个核心问题：

1. 自定义任务未关联编译流程
   你注册的debug是一个全新的BootRun实例，但它没有自动依赖项目的classes任务（负责编译Java源码生成class文件）。当直接运行:core:debug时，Gradle不会自动触发源码编译，导致JVM找不到还未生成的CoreApplication类文件。

2. 未复用Spring Boot插件的默认配置
   默认的bootRun任务会由Spring Boot插件自动配置关键内容：包括包含项目编译输出和依赖的classpath、继承springBoot块定义的mainClass等。但你的自定义debug任务完全手动配置，没有关联这些默认规则，可能导致classpath缺失编译后的类文件。

二、正确配置方案 #

推荐两种简洁可靠的配置方式，优先选择第一种（复用默认配置，减少重复代码）：

方案1：基于默认bootRun扩展调试任务（推荐） #

不需要从零开始定义任务，直接复用默认bootRun的所有配置，仅添加调试相关参数：

// core/build.gradle
import org.springframework.boot.gradle.tasks.run.BootRun

// 保留Spring Boot主类配置，统一管理
springBoot {
    mainClass.set('ru.development.core.CoreApplication')
}

// 基于默认bootRun任务创建debug任务
tasks.register('debug', BootRun) {
    group = 'application'
    description = 'Run Spring Boot with debug enabled'
    
    // 1. 强制依赖编译任务，确保先生成class文件
    dependsOn tasks.named('classes')
    
    // 2. 复用默认bootRun的所有配置（classpath、mainClass等）
    from tasks.named('bootRun')
    
    // 3. 添加调试和环境参数
    args.add('--spring.profiles.active=dev')
    jvmArgs.add('-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005')
}

方案2：手动配置classpath与依赖（适合完全自定义场景） #

如果需要完全控制任务细节，可以显式指定classpath并关联编译任务：

// core/build.gradle
import org.springframework.boot.gradle.tasks.run.BootRun

springBoot {
    mainClass.set('ru.development.core.CoreApplication')
}

tasks.register('debug', BootRun) {
    group = 'application'
    description = 'Run Spring Boot with debug'
    
    // 1. 依赖编译任务，确保class文件已生成
    dependsOn tasks.named('classes')
    
    // 2. 显式配置classpath（包含项目编译输出和所有依赖库）
    classpath = sourceSets.main.runtimeClasspath
    
    // 3. 配置调试与运行参数
    args = ['--spring.profiles.active=dev']
    jvmArgs = ['-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005']
    
    // 4. 复用统一配置的主类，避免硬编码重复
    mainClass.set(springBoot.mainClass.get())
}

三、额外优化建议 #

1. 避免重复配置：在根项目的subprojects块中已经应用了Spring Boot插件，因此core模块的springBoot块配置会被全局识别，无需在自定义任务中重复硬编码mainClass。

2. 验证任务依赖：可以通过运行gradlew :core:tasks --all查看debug任务的依赖关系，确认它已关联classes任务。

3. 临时调试替代方案：如果不想新建任务，也可以直接通过命令行给默认bootRun添加参数：

   gradlew :core:bootRun --args='--spring.profiles.active=dev' --jvmArgs='-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005'
   

内容来源于stack exchange