中文亂碼是 Java Web 開發最經典的坑。本質上是**編碼/解碼不一致**導致:瀏覽器編碼 → HTTP 傳輸 → Servlet 解碼 → Java 字串 (UTF-16) → JDBC 驅動編碼 → MySQL 儲存編碼 → 讀取逆向過程。任一環節不匹配即產生亂碼。本文提供**全鏈路 UTF-8 統一**標準化方案,一勞永逸。
request.getParameter() 解碼編碼。<!-- server.xml -->
<Connector port="8080" protocol="HTTP/1.1"
URIEncoding="UTF-8"
useBodyEncodingForURI="true" />
URIEncoding="UTF-8" 解決 GET 請求 URL 中中文參數解碼;useBodyEncodingForURI 讓 POST 請求體也按此編碼 (配合 request.setCharacterEncoding)。
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 環境)。
<%@ page pageEncoding="UTF-8" contentType="text/html;charset=UTF-8" %>
<%-- pageEncoding: JSP 檔案本身編碼 (編譯時讀取)
contentType: 回應 Content-Type 標頭 (執行時輸出) --%>
<head>
<meta charset="UTF-8"> <!-- HTML5 簡寫,等同 http-equiv Content-Type -->
</head>
關鍵:MySQL utf8 偽 UTF-8 (最多 3 位元組,**不支援 Emoji/生僻字**),必須使用 utf8mb4 (真正 UTF-8,4 位元組)。
-- 建庫
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;
jdbc:mysql://127.0.0.1:3306/myapp?
useSSL=false&
serverTimezone=Asia/Taipei&
allowPublicKeyRetrieval=true&
characterEncoding=utf8mb4& -- 驅動發送/接收編碼
connectionCollation=utf8mb4_unicode_ci -- 連線校對規則
[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)。
<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 Headers | Content-Type: application/x-www-form-urlencoded; charset=UTF-8 |
| Servlet 解碼 | Filter 中 request.getCharacterEncoding() | UTF-8 |
| JSP 輸出編碼 | Response Headers | Content-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 編碼位元組) |
characterEncoding=utf8mb4;驅動版本 5.1.x 需 useUnicode=true&characterEncoding=utf8 (舊驅動不支援 utf8mb4 參數值,需升級 8.0+)。SET NAMES utf8mb4,檢查連線池初始化 SQL (connectionInitSql) 或 my.cnf init_connect。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") 這類「修補大法」,從源頭統一編碼才是專業工程師的態度。