Gradle报错：无法从非build.gradle文件解析导入的DokkaTask类

我有一个单独的docs.gradle文件，内容如下：

apply plugin: "org.jetbrains.dokka"

import org.jetbrains.dokka.gradle.DokkaTask
....

我在模块级的build.gradle中通过apply from: '../gradle/docs.gradle'引入这个脚本，但编译时出现错误：

Could not compile script ...
script <path to docs.gradle> : 3: unable to resolve class org.jetbrains.dokka.gradle.DokkaTask

但如果把import org.jetbrains.dokka.gradle.DokkaTask这句放到根目录或模块级的build.gradle文件中，就能正常识别类。完整异常信息如下：

* Exception is:
org.gradle.groovy.scripts.ScriptCompilationException: Could not compile script '..../gradle/docs.gradle'.
    at org.gradle.groovy.scripts.internal.DefaultScriptCompilationHandler.wrapCompilationFailure(DefaultScriptCompilationHandler.java:192)
    at org.gradle.groovy.scripts.internal.DefaultScriptCompilationHandler.compileScript(DefaultScriptCompilationHandler.java:141)
    at org.gradle.groovy.scripts.internal.DefaultScriptCompilationHandler.compileToDir(DefaultScriptCompilationHandler.java:95)
    at org.gradle.groovy.scripts.internal.BuildOperationBackedScriptCompilationHandler$2.run(BuildOperationBackedScriptCompilationHandler.java:54)
    at org.gradle.internal.operations.DefaultBuildOperationRunner$1.execute(DefaultBuildOperationRunner.java:29)
    at org.gradle.internal.operations.DefaultBuildOperationRunner$1.execute(DefaultBuildOperationRunner.java:26)
    at org.gradle.internal.operations.DefaultBuildOperationRunner$2.execute(DefaultBuildOperationRunner.java:66)
    at org.gradle.internal.operations.DefaultBuildOperationRunner$2.execute(DefaultBuildOperationRunner.java:59)
    at org.gradle.internal.operations.DefaultBuildOperationRunner.execute(DefaultBuildOperationRunner.java:157)
    at org.gradle.internal.operations.DefaultBuildOperationRunner.execute(DefaultBuildOperationRunner.java:59)
    at org.gradle.internal.operations.DefaultBuildOperationRunner.run(DefaultBuildOperationRunner.java:47)
    at org.gradle.internal.operations.DefaultBuildOperationExecutor.run(DefaultBuildOperationExecutor.java:68)

问题出在Gradle编译外部脚本的类路径加载时机上：

• 若你在build.gradle里用plugins块声明Dokka插件，插件的类只会被添加到当前项目脚本的类路径中。
• 外部脚本（docs.gradle）在编译阶段，还未获取到项目脚本加载的插件类路径，导致编译器无法解析DokkaTask类。
• 直接在build.gradle中写导入语句时，类路径已包含插件依赖，所以能正常识别。

以下是几种可行的解决办法：

方法一：在外部脚本中显式声明插件依赖 #

在docs.gradle开头添加buildscript块，手动引入Dokka插件的依赖，确保编译脚本时能找到类：

buildscript {
    repositories {
        mavenCentral() // 或gradlePluginPortal()，根据你的仓库配置选择
    }
    dependencies {
        classpath "org.jetbrains.dokka:dokka-gradle-plugin:1.9.10" // 替换为你实际使用的版本
    }
}

apply plugin: "org.jetbrains.dokka"

import org.jetbrains.dokka.gradle.DokkaTask

// 你的Dokka配置代码

方法二：避免导入，使用全限定类名或类型匹配 #

不需要导入类，直接在配置任务时使用全限定类名，或者通过tasks.withType匹配任务类型：

apply plugin: "org.jetbrains.dokka"

// 方式1：用全限定类名配置单个任务
tasks.named("dokkaHtml", org.jetbrains.dokka.gradle.DokkaTask) {
    // 配置内容
}

// 方式2：通过类型匹配批量配置所有Dokka任务
tasks.withType(org.jetbrains.dokka.gradle.DokkaTask) {
    // 通用配置
}

方法三：拆分插件应用与配置逻辑 #

把插件的应用和导入语句放在模块级或根目录的build.gradle中，外部脚本只保留Dokka的配置内容：

1. 在模块build.gradle中：

plugins {
    id "org.jetbrains.dokka" version "1.9.10"
}

import org.jetbrains.dokka.gradle.DokkaTask

apply from: '../gradle/docs.gradle'

2. 在docs.gradle中只写配置：

// 直接配置DokkaTask，无需导入
tasks.named("dokkaHtml") {
    // 配置内容
}

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