Eclipse 通過 Javadoc 工具生成 API 文檔時，若編碼設置不當，輸出 HTML 易出現中文亂碼。根因在於兩個關鍵參數分別控制「讀取源碼編碼」與「輸出 HTML 編碼」，且需與源文件實際編碼保持一致。本文給出標準配置步驟與原理解析。
| 參數 | 作用 | 典型值 |
|---|
-encoding <charset> | 指定 Javadoc 讀取 .java 源文件時使用的編碼 | UTF-8, GBK |
-charset <charset> | 指定生成 HTML 文件的編碼，並會在 HTML <head> 寫入 <meta http-equiv="Content-Type" content="text/html; charset=..."> | UTF-8, GBK |
Eclipse 圖形界面配置步驟 (推薦)
- 右鍵項目 → Generate Javadoc...
- 對話框中 Javadoc command 確認指向 JDK
bin/javadoc.exe。
- 在 Extra Javadoc options (或 VM options / Other options 視版本而定) 輸入：
-encoding UTF-8 -charset UTF-8 -docencoding UTF-8
-docencoding 為 Javadoc 1.4+ 別名，功能同 -charset，建議三者同寫以兼容舊版本。
- 確認 Destination 輸出目錄，點 Finish。
命令行驗證 (排查利器)
cd <project_root>
javadoc -encoding UTF-8 -charset UTF-8 -d ./doc -sourcepath ./src com.mypkg
若命令行正常、Eclipse 異常，檢查 Eclipse eclipse.ini 中 -Dfile.encoding 或項目屬性 Resource → Text file encoding 是否為 UTF-8。
生成 HTML 頭部標籤示例 (UTF-8)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "https://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
<META http-equiv="Content-Type" content="text/html; charset=utf-8">
<TITLE>MyClass</TITLE>
</HEAD>...
瀏覽器據此正確渲染中文。
常見坑點避雷
- 源文件非 UTF-8：項目屬性設置為 GBK，但 Javadoc 參數給 UTF-8 → 讀取階段解碼錯誤。原則：參數必須匹配源文件實際編碼。
- 僅設置一個參數：只給
-encoding 不給 -charset → 源碼讀對了，但 HTML 無 meta 標籤，瀏覽器可能按系統默認編碼 (如 GBK) 渲染 → 亂碼。
- 項目編碼與文件編碼不一致：Eclipse 項目設置 UTF-8，但部分文件實為 GBK (或反之) → 該文件生成亂碼。建議統一項目為 UTF-8，並用
File → Properties → Resource → Text file encoding = UTF-8 強制一致。
- Ant/Maven 任務未傳遞參數：
<javadoc encoding="UTF-8" docencoding="UTF-8" charset="UTF-8"/> 三屬性均需設置。
最佳實踐清單
- 專案統一採用 UTF-8 無 BOM 編碼 (Git/IDE 默認友好)。
- Eclipse:
Window → Preferences → General → Workspace → Text file encoding = UTF-8。
- Generate Javadoc 對話框固定勾選/輸入
-encoding UTF-8 -charset UTF-8 -docencoding UTF-8。
- 構建腳本 (Ant/Maven/Gradle) 同步配置三參數。
- 生成後用瀏覽器打開
index.html 抽樣驗證中文顯示。
遵循「源碼編碼、讀取參數、輸出編碼、HTML 聲明」四位一體，即可徹底消除 Javadoc 中文亂碼。
- 上一篇文章： 基於 JCA 與 CICS Transaction Gateway 的事務集成深度解析
- 下一篇文章： J2EE 1.4 消息規範變更詳解：JMS 1.1、MDB 2.1 與消息目標新機制
Copyright ©
程式碼之家 All Rights Reserved
