您现在的位置：程式碼之家 >> 編程語言 > >> Java 程式設計 >> Java 相關知識

Java/J2EE 中文亂碼終極解決方案：統一 UTF-8 全鏈路實戰

編輯：Java 相關知識

亂碼根因：跨平台特性導致的編碼不確定性

Java 內部以 UTF-16 處理字串，但 I/O 操作（檔案、網路、資料庫、編譯）依賴作業系統預設編碼。J2EE 環境涉及瀏覽器、Web 容器、JVM、資料庫、作業系統多層轉碼，任一環節不一致即產生亂碼。傳統方案（String.getBytes()/new String() 轉碼、容器配置編碼）皆治標不治本，且破壞封裝或違背容器與應用分離原則。

核心原則：應用層強制統一 UTF-8

UTF-8 相容所有語言、無平台綁定、為 Web 標準編碼。解決之道是在應用程式掌控的所有輸入/輸出邊界，強制指定 UTF-8，不依賴外部環境預設值。

五大關鍵邊界與對應措施

1. 原始碼編譯階段

IDE 專案屬性設定 Encoding = UTF-8（Eclipse：Resource → Text file encoding；IntelliJ：File Encodings）。
javac -encoding UTF-8 或 Ant/Maven/Gradle 編譯任務指定 encoding="UTF-8"。

2. HTTP 請求解碼（Servlet Filter 統一攔截）

public class SetCharacterEncodingFilter implements Filter {
    private String encoding = "UTF-8";
    public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain)
            throws IOException, ServletException {
        if (req.getCharacterEncoding() == null) {
            req.setCharacterEncoding(encoding);
        }
        chain.doFilter(req, res);
    }
    // init/destroy 略
}

web.xml 配置：

<filter>
    <filter-name>encodingFilter</filter-name>
    <filter-class>com.example.SetCharacterEncodingFilter</filter-class>
    <init-param><param-name>encoding</param-name><param-value>UTF-8</param-value></init-param>
</filter>
<filter-mapping><filter-name>encodingFilter</filter-name><url-pattern>/*</url-pattern></filter-mapping>

原理：瀏覽器提交表單編碼不一（IE 預設系統編碼、Firefox/Chrome 多為 UTF-8），Filter 在讀取參數前強制設定，確保 request.getParameter() 正確解碼。

3. JSP 頁面輸出編碼

<%@ page contentType="text/html;charset=UTF-8" %>
<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
</head>

雙重保險：page 指令控制 ServletResponse 編碼，meta 標籤告知瀏覽器解碼方式。

4. 資料庫連線編碼

MySQL 範例：

jdbc:mysql://localhost:3306/mydb?useUnicode=true&characterEncoding=UTF-8&autoReconnect=true

Oracle：確認資料庫字元集為 AL32UTF8，JDBC 驅動 11g+ 自動協商。
PostgreSQL：?charSet=UTF-8。
通用：資料庫層面建立資料庫/表時指定 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci（支援 Emoji）。

5. 其他 I/O 邊界

檔案讀寫：new InputStreamReader(new FileInputStream(file), "UTF-8")
XML 處理：確保 XML 宣告 <?xml version="1.0" encoding="UTF-8"?>，解析器自動處理。
Web Service：SOAP 訊息預設 UTF-8，若對接舊系統需轉碼，在攔截器統一處理。

驗證清單：部署前必檢項目

層級	檢查點	驗證方式
編譯	class 檔案字串常數池編碼	`javap -v ClassName \| grep CONSTANT_Utf8`
請求	中文參數正確解碼	Logger 印出 `request.getParameter("name")`
響應	瀏覽器顯示正常	開發者工具 Network → Response Headers: `Content-Type: text/html;charset=UTF-8`
資料庫	中文存取正確	DB Client 查詢原始位元組 `HEX(column)`
日誌	Log4j/Logback 輸出正常	Appender 設定 `encoding="UTF-8"`

框架整合無痛遷移

作者實戰經驗：Struts、Tapestry、EJB、Hibernate、Jdon 等主流框架，套用上述五大邊界統一 UTF-8 後，從未遇過框架層面的編碼衝突。關鍵在於「在框架之前」透過 Filter、配置、啟動參數建立 UTF-8 執行環境。

常見誤區與避坑指南

誤區：在 Controller/Service 手動 new String(bytes, "ISO-8859-1").getBytes("UTF-8")。正解：Filter 已解決，業務代碼零處理。
誤區：依賴 Tomcat URIEncoding="UTF-8" 解決 GET 亂碼。正解：僅修正 URL 參數，POST Body 需 Filter；且違背應用可移植性。
誤區：資料庫字元集設為 GBK/Big5 因應中文。正解：鎖定單一語系，違背國際化；UTF-8 一勞永逸。