徹底解決 JSP/Servlet 中文亂碼：Filter 統一編碼方案

JSP 與 Servlet 開發中，中文亂碼是經典痛點。雖然可在每個 JSP 加 pageEncoding、每個 Servlet 呼叫 request.setCharacterEncoding()，但易遺漏且維護困難。最佳實務是採用 Filter 統一攔截所有請求，在進入業務邏輯前強制設定編碼，一次設定、全域生效。

核心原則：編碼前後一致

• JSP 頁面指令：<%@ page pageEncoding="UTF-8" %>（或 GB2312/Big5）
• Filter 初始化參數 charset 設為相同編碼
• 資料庫連線、HTML <meta charset>、JS 檔案編碼全數一致

完整 Filter 實作

1. CharsetFilter.java

package com;

import java.io.IOException;
import javax.servlet.*;

public class CharsetFilter implements Filter {
    private String charset = "UTF-8"; // 預設 UTF-8，可由 web.xml 覆寫

    public void destroy() {}

    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
            throws IOException, ServletException {
        // 關鍵：在讀取參數前設定編碼
        request.setCharacterEncoding(charset);
        // 可選：統一回應編碼
        response.setCharacterEncoding(charset);
        chain.doFilter(request, response);
    }

    public void init(FilterConfig config) throws ServletException {
        String cfg = config.getInitParameter("charset");
        if (cfg != null && !cfg.trim().isEmpty()) {
            charset = cfg.trim();
        }
        System.out.println("字符過濾器啟動，編碼：" + charset);
    }
}

2. web.xml 部署描述符

<filter>
    <filter-name>CharsetFilter</filter-name>
    <filter-class>com.CharsetFilter</filter-class>
    <init-param>
        <param-name>charset</param-name>
        <param-value>UTF-8</param-value> <!-- 與 JSP pageEncoding 一致 -->
    </init-param>
</filter>
<filter-mapping>
    <filter-name>CharsetFilter</filter-name>
    <url-pattern>/*</url-pattern> <!-- 攔截所有請求 -->
</filter-mapping>

關鍵細節補充

• 順序很重要：request.setCharacterEncoding() 必須在 request.getParameter() 或 request.getReader() 之前呼叫，Filter 天然滿足此條件。
• POST vs GET：POST 請求體編碼由 Filter 解決；GET 參數在 URL 中，Tomcat 8+ 需在 server.xml <Connector> 加 URIEncoding="UTF-8"。
• 回應編碼：同步設定 response.setCharacterEncoding() 並輸出 Content-Type: text/html; charset=UTF-8，避免瀏覽器誤判。
• 資料庫層：JDBC URL 加 characterEncoding=UTF-8，表/欄位 Collation 同步。

驗證清單

1. JSP 頁面儲存為 UTF-8 無 BOM，且含 pageEncoding="UTF-8"。
2. Filter 類編譯無誤，web.xml 映射 /*。
3. Tomcat server.xml URIEncoding="UTF-8"。
4. 資料庫連線字串含 characterEncoding=UTF-8。
5. 前端 <meta charset="UTF-8">。

完成上述配置，專案中文亂碼問題將徹底解決，新增頁面無需重複設定，維護成本大幅降低。