Javadoc中文编码与生成教程

本文详解了Java项目中使用Javadoc生成含中文注释API文档时避免乱码的核心实践——必须严格统一源文件编码、Javadoc解析编码（-encoding）和HTML输出编码（-docencoding）三者为UTF-8，涵盖IDE配置、命令行参数、Maven插件及Gradle任务的完整设置方案，帮你轻松解决中文注释显示异常、编译报错等常见痛点，让专业API文档清晰、规范、开箱即用。

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，中文注释就能清晰呈现。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Javadoc中文编码与生成教程》文章吧，也可关注golang学习网公众号了解相关技术文章。