OpenJDK 自带 javadoc 工具，只需正确配置 JAVA_HOME 和 PATH 即可使用；需验证版本一致性、指定 UTF-8 编码、合理设置 sourcepath 与 subpackages，并注意 doclint 严格检查及中文乱码等问题。
OpenJDK 自带 javadoc 工具，不需要额外安装——只要你的 JAVA_HOME 指向 OpenJDK（比如 /usr/lib/jvm/java-17-openjdk-amd64 或 C:\Program Files\Java\jdk-17），就能直接用命令行生成项目文档。
确认 javadoc 可用且版本匹配
先验证环境是否就绪，避免“命令未找到”或“版本不兼容”问题：
- 终端运行
javadoc -version，输出应与java -version一致（如17.0.1）；若报错，说明JAVA_HOME/bin未加入PATH - OpenJDK 11+ 默认启用
doclint严格检查，遇到注释格式瑕疵（比如@param缺失、HTML 标签未闭合）会直接中断生成，不是静默跳过 - 中文注释必须显式指定编码，否则生成的 HTML 里全是乱码，
-encoding UTF-8 -charset UTF-8不可省略
单模块项目：用 sourcepath + subpackages 最稳
不要直接 javadoc *.java —— 这只处理当前目录，且无法解析包结构和跨文件引用（比如 {@link OtherClass} 会失效）。
- 假设源码在
src/main/java，主包是com.example.myapp，执行： javadoc -d docs/api -sourcepath src/main/java -subpackages com.example.myapp -encoding UTF-8 -charset UTF-8 -private-
-subpackages保证子包（如com.example.myapp.service）一并扫描，-private才能包含私有方法文档（调试/内部工具类常需） - 若提示
No public or protected classes found，大概率是sourcepath路径不对，或源码里没有public class（javadoc默认只处理 public 类）
Maven 项目：用 maven-javadoc-plugin 避免手动维护
手动敲命令易出错，Maven 插件能自动继承项目源路径、模块依赖和编码配置：
Java Maven Common
下载
Java Maven 项目审查工作流的通用输入处理。当 Java Maven 项目以 ZIP压缩包或 GitLab 仓库 URL 形式提供且需要...时使用。
立即学习“Java免费学习笔记（深入）”；
- 在
pom.xml的<build><plugins>中添加：
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.6.0</version>
<configuration>
<encoding>UTF-8</encoding>
<docencoding>UTF-8</docencoding>
<locale>zh_CN</locale>
<doclint>none</doclint>
</configuration>
</plugin>
<doclint>none</doclint> 是关键：关闭 OpenJDK 11+ 的 doclint，否则因注释小瑕疵（如 @param 拼写错误、缺少空行）导致 mvn clean install 失败mvn javadoc:javadoc 即可，文档默认输出到 target/site/apidocs
常见失败原因和绕过方式
生成失败往往卡在几个固定环节，而不是整体流程有问题：
-
error: package xxx does not exist：源码用了其他模块的类，但javadoc没看到它们的 class 或 jar。加-classpath或改用 Maven（自动聚合依赖） - 中文乱码但加了
-encoding UTF-8还不行？检查源文件本身是否真是 UTF-8 编码（Notepad++ 或 VS Code 看右下角编码标识），BOM 头也会干扰 -
index.html打开空白？浏览器可能拦截本地file://协议的 JS/CSS。用python3 -m http.server 8000启个临时服务，访问http://localhost:8000/docs/api/index.html - 生成的页面里
{@link XXX}显示为纯文本？说明目标类没被扫描到，确认它在-subpackages范围内，或已编译进 classpath
真正麻烦的从来不是“怎么生成”，而是让所有开发者写的 @param 和 @return 保持一致、不漏不冗——这得靠 CI 流水线加检查，而不是靠一次 javadoc 命令。
