OpenJDK怎么用javadoc生成项目文档-java教程-PHP中文网

openjdk 自带 javadoc 工具，只需正确配置 java_home 和 path 即可使用；需验证版本一致性、指定 utf-8 编码、合理设置 sourcepath 与 subpackages，并注意 doclint 严格检查及中文乱码等问题。

openjdk怎么用javadoc生成项目文档

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} 会失效）。

Java Maven Common

Java Maven 项目审查工作流的通用输入处理。当 Java Maven 项目以 ZIP压缩包或 GitLab 仓库 URL 形式提供且需要...时使用。

下载

假设源码在 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 插件能自动继承项目源路径、模块依赖和编码配置：

在 pom.xml 的 <build><plugins></plugins></build> 中添加：

<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