Gradle 8.6打包Spring Boot 2.7.6 War时public/docs文件夹缺失

使用Gradle 8.6为Spring Boot 2.7.6项目打包War包，结合asciidoctor.jvm.convert 2.4.0和Spring Docs 2.0.5配置后，War包生成成功，但预期的/public/docs/*.html文件未包含在内。原配置如下：

test {
 useJUnitPlatform()
 outputs.dir snippetsDir
}
asciidoctor {
 configurations "asciidoctorExtensions"
 inputs.dir snippetsDir
 dependsOn test
 doLast {
     copy{
      from ("$buildDir/asciidoc/html5")
      into ("$buildDir/resources/main/public/docs")
  include "**/*.html"
   }
  war {
 enabled = true
 dependsOn asciidoctor
}
}

问题分析 #

• 语法错误：war任务块被错误嵌套在asciidoctor的doLast闭包内，导致War任务的依赖配置未生效。
• 资源拷贝时机：直接在asciidoctor的doLast中拷贝文件到build/resources/main，可能赶不上War任务的资源收集阶段，或该目录未被War任务正确识别。

解决方案 #

方案1：修正语法结构，调整任务层级 #

把war块从asciidoctor的doLast中移出，确保任务依赖关系正确配置：

def snippetsDir = file("build/generated-snippets")

test {
    useJUnitPlatform()
    outputs.dir snippetsDir
}

asciidoctor {
    configurations "asciidoctorExtensions"
    inputs.dir snippetsDir
    dependsOn test
    // 明确指定输出格式和目录，避免路径歧义
    outputDir = file("build/asciidoc/html5")
    backends = ["html5"]
    
    doLast {
        copy {
            from outputDir
            into file("${buildDir}/resources/main/public/docs")
            include "**/*.html"
        }
    }
}

war {
    enabled = true
    // 确保War任务在asciidoctor完成后执行
    dependsOn asciidoctor
}

方案2：绑定资源拷贝到processResources任务（更规范） #

将Asciidoctor生成的HTML文件作为项目资源处理，让processResources任务依赖asciidoctor，确保资源被正确打包：

def snippetsDir = file("build/generated-snippets")
def docsOutputDir = file("${buildDir}/asciidoc/html5")

test {
    useJUnitPlatform()
    outputs.dir snippetsDir
}

asciidoctor {
    configurations "asciidoctorExtensions"
    inputs.dir snippetsDir
    dependsOn test
    outputDir = docsOutputDir
    backends = ["html5"]
}

// 让processResources任务依赖asciidoctor，并将生成的HTML加入资源
processResources {
    dependsOn asciidoctor
    from(docsOutputDir) {
        into "public/docs"
        include "**/*.html"
    }
}

war {
    enabled = true
    // War任务默认依赖processResources，无需额外配置dependsOn asciidoctor
}

验证步骤 #

1. 执行./gradlew clean asciidoctor，检查build/asciidoc/html5下是否生成了目标HTML文件。
2. 执行./gradlew clean war，解压生成的War包，查看WEB-INF/classes/public/docs目录下是否包含预期的HTML文件（Spring Boot War包中，resources下的内容会被打包到WEB-INF/classes路径下）。

内容的提问来源于stack exchange，提问作者Test Email