萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> JSP 程式設計

JSP/Servlet MySQL 中文亂碼終極解決方案:全鏈路 UTF-8 統一

中文亂碼是 Java Web 開發最經典的坑。本質上是**編碼/解碼不一致**導致:瀏覽器編碼 → HTTP 傳輸 → Servlet 解碼 → Java 字串 (UTF-16) → JDBC 驅動編碼 → MySQL 儲存編碼 → 讀取逆向過程。任一環節不匹配即產生亂碼。本文提供**全鏈路 UTF-8 統一**標準化方案,一勞永逸。

亂碼產生的三大關鍵環節

  1. 請求參數解碼:瀏覽器送出表單/URL 參數時的編碼 vs Servlet request.getParameter() 解碼編碼。
  2. 回應內容編碼:JSP/Servlet 輸出位元組流編碼 vs 瀏覽器渲染解碼編碼。
  3. 資料庫存取編碼:JDBC 驅動傳輸編碼 vs MySQL 表/欄位/連線字元集。

第一層:Web 容器與 Servlet 統一 UTF-8

1. Tomcat 連接器強制 URI 編碼 (GET 參數)

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

URIEncoding="UTF-8" 解決 GET 請求 URL 中中文參數解碼;useBodyEncodingForURI 讓 POST 請求體也按此編碼 (配合 request.setCharacterEncoding)。

2. 全域請求/回應編碼過濾器 (最徹底、推薦)

package com.example.filter;

import jakarta.servlet.*;
import jakarta.servlet.annotation.WebFilter;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;

@WebFilter("/*") // 攔截所有請求
public class EncodingFilter implements Filter {
    private static final String ENCODING = "UTF-8";

    @Override
    public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain) 
            throws IOException, ServletException {
        HttpServletRequest request = (HttpServletRequest) req;
        HttpServletResponse response = (HttpServletResponse) res;

        // 1. 請求解碼 (POST 表單、JSON 體)
        if (request.getCharacterEncoding() == null) {
            request.setCharacterEncoding(ENCODING);
        }
        // 2. 回應編碼 (需在獲取 Writer/OutputStream 前設定)
        response.setCharacterEncoding(ENCODING);
        response.setContentType("text/html;charset=" + ENCODING); // JSP 預設

        chain.doFilter(request, response);
    }
}
此 Filter **必須** 在其他 Filter (如 Spring Security、Struts2) **之前** 執行。可在 web.xml 調整 <filter-mapping> 順序或使用 @Order(Ordered.HIGHEST_PRECEDENCE) (Spring 環境)。

3. JSP 頁面指令雙重保險

<%@ page pageEncoding="UTF-8" contentType="text/html;charset=UTF-8" %>
<%-- pageEncoding: JSP 檔案本身編碼 (編譯時讀取)
     contentType: 回應 Content-Type 標頭 (執行時輸出) --%>

4. HTML Meta 標籤 (瀏覽器端兜底)

<head>
    <meta charset="UTF-8"> <!-- HTML5 簡寫,等同 http-equiv Content-Type -->
</head>

第二層:MySQL 資料庫全鏈路 UTF-8 (utf8mb4)

關鍵:MySQL utf8 偽 UTF-8 (最多 3 位元組,**不支援 Emoji/生僻字**),必須使用 utf8mb4 (真正 UTF-8,4 位元組)。

1. 資料庫/表/欄位層級指定

-- 建庫
CREATE DATABASE myapp DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 建表 (繼承資料庫預設,或顯式指定)
CREATE TABLE users (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(50) NOT NULL,
    bio TEXT
) DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

-- 修改既有表/欄位
ALTER TABLE users CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
ALTER TABLE users MODIFY bio TEXT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

2. JDBC 連線字串強制字元集

jdbc:mysql://127.0.0.1:3306/myapp?
    useSSL=false&
    serverTimezone=Asia/Taipei&
    allowPublicKeyRetrieval=true&
    characterEncoding=utf8mb4&       -- 驅動發送/接收編碼
    connectionCollation=utf8mb4_unicode_ci  -- 連線校對規則

3. 伺服器端配置 (my.cnf / my.ini) 永久生效

[client]
default-character-set = utf8mb4

[mysql]
default-character-set = utf8mb4

[mysqld]
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
init_connect = 'SET NAMES utf8mb4'  -- 客戶端連接時自動執行
skip-character-set-client-handshake -- 忽略客戶端聲明字元集,強制使用伺服器設定

修改後 **重啟 MySQL 服務** 生效。驗證:SHOW VARIABLES LIKE 'character_set%'; 全部應為 utf8mb4 (除 character_set_filesystem=binary、character_set_dir)。

第三層:前端表單與 AJAX 同步

<form method="post" action="/submit" accept-charset="UTF-8"> ... </form>

<!-- AJAX (jQuery/Fetch) -->
fetch('/api/save', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json;charset=UTF-8' },
    body: JSON.stringify({ name: '中文' })
});

JSON 標準規範 **必須 UTF-8**,無需額外設定。

驗證清單:從瀏覽器到資料庫

檢查點命令/操作預期結果
瀏覽器發送編碼F12 Network → Request HeadersContent-Type: application/x-www-form-urlencoded; charset=UTF-8
Servlet 解碼Filter 中 request.getCharacterEncoding()UTF-8
JSP 輸出編碼Response HeadersContent-Type: text/html;charset=UTF-8
資料庫連線字元集SHOW SESSION VARIABLES LIKE 'character_set%';client/connection/results/database 皆為 utf8mb4
表/欄位字元集SHOW CREATE TABLE users;DEFAULT CHARSET=utf8mb4
資料實際儲存SELECT HEX(name) FROM users WHERE name='測試';E6 B8 AC E8 AF 95 (UTF-8 編碼位元組)

常見殘留問題排查

  • 唯獨 INSERT 亂碼:檢查 JDBC URL 是否含 characterEncoding=utf8mb4;驅動版本 5.1.x 需 useUnicode=true&characterEncoding=utf8 (舊驅動不支援 utf8mb4 參數值,需升級 8.0+)。
  • 命令列客戶端正常,應用亂碼:應用連線未執行 SET NAMES utf8mb4,檢查連線池初始化 SQL (connectionInitSql) 或 my.cnf init_connect。
  • Linux 伺服器檔案系統編碼:確認 locale -a 含 zh_TW.utf8,JVM 啟動參數 -Dfile.encoding=UTF-8。

結語

**「全鏈路 UTF-8 (utf8mb4)」** 是解決中文亂碼的唯一正解:Tomcat URIEncoding + EncodingFilter + JSP pageEncoding + HTML meta + MySQL utf8mb4 (庫/表/欄/連線) + my.cnf 強制。一次配置,終身受益。拒絕在程式碼中到處 new String(bytes, "ISO-8859-1").getBytes("UTF-8") 這類「修補大法」,從源頭統一編碼才是專業工程師的態度。

copyright © 萬盛學電腦網 all rights reserved