Dokka Gradle 的问题与解决方案

本章介绍在 Gradle 构建中使用 Dokka 生成文档时可能遇到的常见问题.

如果你遇到的问题未在本章列出, 请在我们的问题跟踪系统中提交反馈意见, 或报告问题, 或在官方 Kotlin Slack 中与 Dokka 开发社区交流. 请点击这里获取 Slack 邀请.

内存问题

对于大型项目, Dokka 在生成文档时可能会消耗大量内存. 这可能会超过 Gradle 的内存限制, 尤其是在处理大量数据时.

当 Dokka 生成文档时内存耗尽, 构建将会失败, Gradle 可能会抛出 java.lang.OutOfMemoryError: Metaspace 这样的异常.

目前正在积极改进 Dokka 的性能, 但部分限制来自于 Gradle 本身.

如果你遇到内存问题, 请尝试以下变通方法:

增加堆空间
在 Gradle 进程内运行 Dokka

增加堆空间

解决内存问题的一种方法是增加 Dokka 生成器进程的 Java 堆内存量. 在 build.gradle.kts 文件中, 调整以下配置选项:

    dokka {
        // Dokka 生成一个由 Gradle 管理的新进程
        dokkaGeneratorIsolation = ProcessIsolation {
            // 配置堆大小
            maxHeapSize = "4g"
        }
    }

在这个示例中, 最大堆大小被设置为 4 GB ("4g"). 请调整并测试这个值, 找到适合你的构建的最优设置.

如果你发现 Dokka 需要相当大的堆空间, 例如明显高于 Gradle 本身的内存使用量, 请在 Dokka 的 GitHub 仓库中创建一个 issue.

在 Gradle 进程内运行 Dokka

当 Gradle 构建和 Dokka 生成文档都需要大量内存时, 它们可能会作为独立的进程运行, 在单台机器上消耗大量内存.

为了优化内存使用, 你可以在 Gradle 的同一个进程内运行 Dokka, 而不是作为独立的进程运行. 这样, 只需要为 Gradle 配置一次内存, 而不用为每个进程分别分配内存.

要在 Gradle 的同一个进程内运行 Dokka, 请在 build.gradle.kts 文件中调整以下配置选项:

    dokka {
        // 在当前 Gradle 进程中运行 Dokka
        dokkaGeneratorIsolation = ClassLoaderIsolation()
    }

与增加堆空间一样, 请测试这个配置, 确认它是否适用于你的项目.

关于配置 Gradle JVM 内存的更多详情, 请参见 Gradle 文档.

2026/07/24