Java Web 中文亂碼終極解決方案：全鏈路編碼一致性指南（Servlet、Filter、Tomcat、DB、前端）

亂碼產生的三大入口

1. 請求參數解碼：GET/POST 參數從字節 → 字符串
2. 業務處理/存儲：字符串 → 數據庫/文件/外部 API
3. 響應輸出編碼：字符串 → 字節流 → 瀏覽器

第一階段：請求參數統一解碼（核心難點）

1. POST 請求：Filter 方案（推薦）

@WebFilter("/*")
public class EncodingFilter implements Filter {
    private static final String ENCODING = "UTF-8";

    @Override
    public void doFilter(ServletRequest req, ServletResponse resp, FilterChain chain) 
            throws IOException, ServletException {
        req.setCharacterEncoding(ENCODING);   // 必須在 getParameter() 前調用
        resp.setCharacterEncoding(ENCODING);
        resp.setContentType("text/html;charset=" + ENCODING);
        chain.doFilter(req, resp);
    }
}

• request.setCharacterEncoding() 僅對 Body 參數（POST）生效。
• 必須在 getParameter()、getReader() 之前調用，否則無效。

2. GET 請求：Tomcat URIEncoding（唯一生效）

<!-- Tomcat server.xml -->
<Connector port="8080" protocol="HTTP/1.1"
           URIEncoding="UTF-8" 
           ... />

• GET 參數在 URL 路徑/查詢串，屬於 URI 解碼階段，Filter 無法攔截。
• Tomcat 8+ 默認即為 UTF-8，但建議顯式配置。

3. Spring Boot 統一配置

@Bean
public FilterRegistrationBean encodingFilter() {
    CharacterEncodingFilter filter = new CharacterEncodingFilter();
    filter.setEncoding("UTF-8");
    filter.setForceEncoding(true); // 強制覆蓋 request/response 編碼
    FilterRegistrationBean bean = new FilterRegistrationBean<>(filter);
    bean.addUrlPatterns("/*");
    bean.setOrder(Ordered.HIGHEST_PRECEDENCE);
    return bean;
}

第二階段：業務層字符串處理最佳實踐

第三階段：響應輸出編碼

// Servlet 原生
response.setContentType("text/html;charset=UTF-8");
response.setCharacterEncoding("UTF-8");
PrintWriter out = response.getWriter(); // 獲取 Writer 會鎖定編碼，之後不可改
out.write("中文正常");

// Spring MVC @RestController 默認 application/json;charset=UTF-8
// JSP 頁面頂部
<%@ page contentType="text/html;charset=UTF-8" pageEncoding="UTF-8" %>

全鏈路檢查清單（部署前必驗）

1. ☐ 所有 .java/.jsp/.xml/.properties 文件保存為 UTF-8 無 BOM
2. ☐ IDE 編譯編碼設置為 UTF-8（IntelliJ: Settings → File Encodings → Global/Project/Properties = UTF-8）
3. ☐ Tomcat server.xml URIEncoding="UTF-8"
4. ☐ web.xml 或 Spring Boot 配置 CharacterEncodingFilter（forceEncoding=true）
5. ☐ 數據庫連接串含 characterEncoding=utf8&useUnicode=true
6. ☐ 表/庫字符集 utf8mb4（支持 Emoji）
7. ☐ 前端頁面 <meta charset="UTF-8">、AJAX contentType: "application/json;charset=UTF-8"
8. ☐ 日誌框架 log4j2.xml / logback.xml 設置 charset="UTF-8"

經典誤區還原

總結

中文亂碼本質是編碼/解碼不一致。解決之道只有一條：全鏈路統一 UTF-8（推薦 utf8mb4），在最早入口正確解碼，在最後出口正確編碼，中間業務層純 Unicode 操作，絕不手動轉碼。配置一次，永久安寧。

1. 上一篇文章： Java Thread.join() 線程協作詳解：原理、用法、超時控制與常見誤區
2. 下一篇文章： Java 字符串字符頻率統計：TreeMap 實現、Stream API 一行碼、性能對比與最佳實踐

Java 程式設計入門

一分鐘掌握 Java 8 Lambda 表達式核心原理

從匿名內部類到 Lambda Java 8 前，排序列表需寫

Java 打包部署實戰：Jar 轉 Exe 並製作安裝包 (exe4j + Inno Setup 避坑指南)

工具鏈選型 exe4j：將可執行 Jar 包裝為原生 .e

Java IO 流體系全景深度解析：字節/字符流、裝飾者模式、緩衝、轉換、隨機訪問、NIO/NIO.2 核心原理與選型指南

前言 Java IO 是後端開發的基石，從經典的 java.

JBuilder 2005 Servlet 自動啟動配置實戰：啟動時快取用戶資料

前言 Servlet 區別於 JSP 的關鍵特性：可透過 w