Java Web 中文亂碼終極解決方案：Tomcat、前端代理、URL、JSP、傳輸層全鏈路修復

中文亂碼是 Java Web 開發「必經之痛」，本質是 **編碼不一致** 導致的字節序列錯誤解碼。本文提供 **全鏈路修復指南**，覆蓋 Tomcat 連接器、前端代理、URL 參數、JSP 頁面、網絡傳輸層五大場景，附帶驗證清單與排查流程圖，助你一次性徹底解決亂碼問題。

亂碼本質：編碼-解碼不對稱

字符串 --(編碼 Charset A)--> 字節序列 --(解碼 Charset B)--> 字符串
若 A != B  → 亂碼
Java 內部：UTF-16 (char)
網絡傳輸：ISO-8859-1 (舊規範) / UTF-8 (現代標準)

一、Tomcat 連接器層（HTTP/1.1 & AJP）

1. HTTP 連接器（`server.xml`）

<Connector port="8080" protocol="HTTP/1.1"
           connectionTimeout="20000"
           redirectPort="8443"
           URIEncoding="UTF-8" />  <!-- 關鍵：強制 URI 解碼為 UTF-8 -->

• `URIEncoding="UTF-8"`：作用於 **GET 請求 URL 路徑/查詢參數** 的解碼。
• POST 請求體編碼由 `request.setCharacterEncoding("UTF-8")` 控制（見下文）。

2. AJP 連接器（前端 Nginx/Apache 代理時）

<Connector port="8009" protocol="AJP/1.3"
           redirectPort="8443"
           URIEncoding="UTF-8" />  <!-- 必須同步設置 -->

• AJP 協議同樣傳遞 URI 字節流，若不指定 `URIEncoding`，Tomcat 默認 ISO-8859-1 解碼 → 亂碼。

二、URL 參數編碼/解碼（GET/POST 請求參數）

前端編碼（JavaScript）

// 單個參數值編碼
const encodedValue = encodeURIComponent(value);  // RFC 3986，空格→%20，不編碼 - _ . ~

// 整個 URL 查詢串構建
const params = new URLSearchParams();
params.append('title', '中文標題');
params.append('author', '張三');
const url = `/api/articles?${params.toString()}`;  // 瀏覽器自動處理

後端解碼（Servlet/Controller）

// 通用：Spring MVC / Servlet 3.0+ 容器自動按 URIEncoding 解碼 GET 參數
// 若無 Spring，手動解碼：
String decoded = java.net.URLDecoder.decode(request.getParameter("title"), StandardCharsets.UTF_8.name());

// POST 表單/JSON 體：必須在讀取參數前設置
request.setCharacterEncoding("UTF-8");  // 僅影響 request.getParameter()、request.getReader()

雙重編碼陷阱

• 前端 `encodeURIComponent` + 後端再次 `URLDecoder.decode` → 正常。
• 前端 `encodeURIComponent` + 後端容器自動解碼 + 手動再次 `decode` → **雙重解碼** → 亂碼/異常。
• **約定**：單邊編碼/解碼，通常前端編碼、容器/框架自動解碼，業務代碼**不再手動解碼**。

三、JSP 頁面編碼

頁面指令（必須在第一行）

<%@ page language="java" contentType="text/html; charset=UTF-8"
         pageEncoding="UTF-8" %>

• `contentType`：HTTP 響應頭 `Content-Type: text/html; charset=UTF-8`，告訴瀏覽器以 UTF-8 顯示。
• `pageEncoding`：JSP 文件本身的保存編碼，編譯時按此讀取源碼。

若仍亂碼，強制轉碼（不推薦，治標不治本）

String fixed = new String(broken.getBytes("ISO-8859-1"), "UTF-8");

原理：錯誤按 ISO-8859-1 解碼產生的字符串，其內部字節實為 UTF-8 字節，重新按 ISO-8859-1 編碼取回原字節，再按 UTF-8 正確解碼。

四、網絡傳輸層編碼協議

現代框架（Spring MVC、Jakarta EE 8+）已內部處理，業務代碼**無需手動轉碼**，只需確保 Tomcat `URIEncoding=UTF-8` 及請求/響應 `Content-Type` 正確。

五、數據庫連接編碼

-- MySQL (JDBC URL)
jdbc:mysql://localhost:3306/db?characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai

-- PostgreSQL
jdbc:postgresql://localhost:5432/db?charSet=UTF-8

-- 連接池
spring.datasource.hikari.connectionInitSql=SET NAMES utf8mb4

• 數據庫、表、列編碼均建議 `utf8mb4`（支援 Emoji）。
• JDBC URL 顯式指定 `characterEncoding` 避免驅動默認值差異。

六、驗證清單（部署後必查）

1. [ ] `server.xml` HTTP/AJP Connector 均有 `URIEncoding="UTF-8"`
2. [ ] JSP 頁面首行 `pageEncoding="UTF-8" contentType="text/html; charset=UTF-8"`
3. [ ] 所有 HTML 頁面 ``
4. [ ] JavaScript 參數構建用 `encodeURIComponent` / `URLSearchParams`
5. [ ] Spring MVC / Filter 鏈中 `CharacterEncodingFilter` 註冊且 `forceEncoding=true`
6. [ ] 數據庫 JDBC URL 含 `characterEncoding=utf8` / `charSet=UTF-8`
7. [ ] 文件保存編碼統一 UTF-8（IDE 設置：Settings → File Encodings → Global/Project/Properties = UTF-8）
8. [ ] 測試用例覆蓋：中文路徑參數、POST 表單、JSON 體、Emoji、特殊符號

七、排查流程圖（文字版）

發現亂碼
   │
   ├─ 請求參數亂碼？
   │    ├─ GET → 檢查 Tomcat URIEncoding、前端 encodeURIComponent、雙重解碼
   │    └─ POST → 檢查 request.setCharacterEncoding、CharacterEncodingFilter
   │
   ├─ 響應頁面亂碼？
   │    ├─ JSP → 檢查 pageEncoding、contentType、meta charset
   │    ├─ 靜態資源 → 檢查 Nginx/Apache charset、Tomcat 默認 Servlet
   │    └─ AJAX/JSON → 檢查 @ResponseBody/ResponseEntity charset、產出 Content-Type
   │
   ├─ 數據庫存取亂碼？
   │    └─ 檢查 JDBC characterEncoding、數據庫/表/列 utf8mb4、連接池 initSql
   │
   └─ 文件上傳/下載亂碼？
        └─ 檢查 MultipartResolver 編碼、Content-Disposition filename 編碼 (RFC 5987)

八、Spring Boot 一鍵配置

# application.yml
server:
  servlet:
    encoding:
      charset: UTF-8
      force: true
      enabled: true  # 自動註冊 CharacterEncodingFilter

spring:
  http:
    encoding:
      charset: UTF-8
      force: true
  datasource:
    url: jdbc:mysql://localhost:3306/db?characterEncoding=utf8&useSSL=false
    hikari:
      connectionInitSql: SET NAMES utf8mb4

中文亂碼無銀彈，只有 **全鏈路統一 UTF-8** 才是正解。按本文清單逐項落地，配合自動化測試驗證，即可從根源消除亂碼，讓團隊專注業務創新。