Java项目用Javadoc生成含中文注释的API文档时，需统一源文件、Javadoc读取及HTML输出编码为UTF-8：确保源码存为UTF-8，IDE配置对应编码，命令行加-encoding和-docencoding参数，Maven/Gradle插件中同步设置三者。
Java 项目用 Javadoc 生成 API 文档时，如果源码含中文注释，默认可能显示乱码或报错，核心原因是编码不一致——源文件是 UTF-8，但 Javadoc 工具默认按平台编码（如 Windows 的 GBK）读取，导致解析失败。
确保源文件本身是 UTF-8 编码
这是前提。IDE（如 IntelliJ 或 Eclipse）需将 Java 文件保存为 UTF-8 格式：
- IntelliJ：File → Settings → Editor → File Encodings → Global Encoding / Project Encoding → 设为 UTF-8，同时勾选 “Transparent native-to-ascii conversion”（避免 \uXXXX 转义）
- Eclipse：右键项目 → Properties → Resource → Text file encoding → 选择 UTF-8
- 用记事本或 VS Code 打开 .java 文件时，确认右下角显示 “UTF-8”，而非 ANSI/GBK
命令行执行 Javadoc 时显式指定编码
直接调用 javadoc 命令必须加 -encoding 和 -docencoding 参数：
-
-encoding UTF-8：告诉 Javadoc 按 UTF-8 解析源文件内容 -
-docencoding UTF-8：指定生成的 HTML 文件内部声明的字符编码（影响浏览器正确渲染） - 完整示例：
javadoc -encoding UTF-8 -docencoding UTF-8 -charset UTF-8 -d docs src/com/example/*.java
注意：-charset 非必需，但加上可确保 HTML 的 正确写入，增强兼容性。
Maven 项目中配置 maven-javadoc-plugin
在 pom.xml 中配置插件时，需设置
<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><charset>UTF-8</charset></configuration></plugin>
运行 mvn javadoc:javadoc 即可正确处理中文。
Gradle 项目中的等效配置
在 build.gradle 中为 javadoc 任务添加选项：
javadoc {
options.encoding = 'UTF-8'
options.docEncoding = 'UTF-8'
options.charSet = 'UTF-8'
// 若使用新版本 Gradle（如 8.0+），还需显式设置工具链
if (JavaVersion.current().isJava17Compatible()) {
options.addStringOption('source', '17')
}
}
执行 ./gradlew javadoc 后，build/docs/javadoc/ 下的 HTML 就能正常显示中文。
不复杂但容易忽略：三个编码参数各司其职，缺一不可；只要源码、读取、输出三者统一为 UTF-8，中文注释就能清晰呈现。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
