Javadoc任务需显式配置编码与可见性：设options.encoding、docEncoding、charSet均为UTF-8，指定memberLevel为PRIVATE以包含私有成员，并禁用Xdoclint确保构建稳定。
javadoc 任务默认已由 Gradle 的 java 插件注册，但不自动执行，且默认配置对中文注释、私有成员、外部链接等场景完全不友好——直接运行 ./gradlew javadoc 很可能报错或生成乱码页面。
javadoc 任务必须显式配置编码和可见性
Gradle 不会继承系统或 IDE 的编码设置，源文件是 UTF-8，但 javadoc 默认用平台编码（如 Windows 的 GBK）读取，导致解析失败或中文注释显示为方块。
-
必须在
build.gradle中为javadoc任务设置三项编码参数：-
options.encoding = "UTF-8"：告诉 Javadoc 按 UTF-8 解析源码 -
options.docEncoding = "UTF-8"：指定生成 HTML 的<meta charset> -
options.charSet = "UTF-8"：确保浏览器渲染正确（虽非强制，但缺它在某些环境仍乱码）
-
-
若需包含
protected或private成员文档（例如内部 SDK 文档），加：立即学习“Java免费学习笔记（深入）”；
options.memberLevel = JavadocMemberLevel.PRIVATE
排除内部实现包（如
<strong>/internal/</strong>）可避免泄露敏感逻辑，用exclude配合sourceSets.main.java.srcDirs。
javadoc 命令行参数要映射到 Gradle DSL
Gradle 的 javadoc 任务底层调用的是 JDK 的 javadoc 工具，但不能直接写命令行参数字符串（比如 -Xdoclint:none），必须用 DSL 方法或 addStringOption。
-
禁用 doclint（避免因 @param 缺失等格式问题导致构建失败）：
options.addStringOption("Xdoclint:none", "-quiet")
-
添加 Oracle 官方 API 链接（让
@link能跳转）：options.links("<a href="https://www.php.cn/link/ed2fb6eafdea28225b0158f329681aa3">https://www.php.cn/link/ed2fb6eafdea28225b0158f329681aa3</a>")
-
设置窗口标题和页眉（影响生成 HTML 的
<title>和顶部 banner）：options.windowTitle = "MyLib API"options.header = "MyLib ${version}"
输出目录不要硬编码，用
destinationDir = file("$buildDir/docs/javadoc")更可靠。
中文环境下最容易被忽略的三个点
源文件本身不是 UTF-8，一切配置都白搭
IntelliJ：Settings → Editor → File Encodings → 全局/项目编码设为 UTF-8，并勾选 “Transparent native-to-ascii conversion”；VS Code 打开 .java 文件右下角必须显示 “UTF-8”。javadoc任务默认只处理main源集，如果你有多个 sourceSet（如integrationTest），它不会自动扫描——要手动source = sourceSets.integrationTest.allJava。-
Gradle 7+ 默认启用
--no-daemon模式时，javadoc可能因内存不足卡死或 OOM，建议在gradle.properties加：org.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=512m
生成文档前务必确认这三件事：源码存为 UTF-8、build.gradle 里写了三项 encoding、./gradlew clean javadoc 是完整命令（clean 防止旧缓存干扰）。其他定制（如自定义 Doclet、多模块聚合）属于进阶需求，基础场景按上述配好就能稳定输出可用文档。
