JSP 文件上傳中文文件名亂碼終極解決：字符編碼鏈路全鏈路排查指南

亂碼現場

• JSP 頁面：contentType="text/html; charset=UTF-8"
• Eclipse 工作空間：Text file encoding = GBK
• 操作系統：Windows (默認 GBK/CP936)
• 現象：request.getParameter("filename") 獲取中文文件名顯示 ????，控制台輸出亂碼。

編碼鏈路拆解

文件上傳涉及三層編碼轉換：

1. 瀏覽器發送： 表單 enctype="multipart/form-data" 時，瀏覽器按頁面 charset (UTF-8) 編碼文件名，放入請求體。
2. 容器解析： Tomcat/DefaultServlet 解析 multipart 請求，需配置 URIEncoding="UTF-8" (Tomcat 8+ 默認 UTF-8) 並設置 request.setCharacterEncoding("UTF-8") **在讀取參數前**。
3. Java 代碼處理： String name = request.getParameter("filename") 獲取已解碼的 Unicode 字符串，後續寫入磁盤/數據庫需統一 UTF-8。

核心修復清單

1. Tomcat server.xml： <Connector port="8080" URIEncoding="UTF-8" />
2. Filter 統一編碼 (最穩健)：

   @WebFilter("/*")
   public class EncodingFilter implements Filter {
       public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain) {
           req.setCharacterEncoding("UTF-8");
           res.setCharacterEncoding("UTF-8");
           chain.doFilter(req, res);
       }
   }
   

3. JSP 頁面指令： <%@ page contentType="text/html;charset=UTF-8" pageEncoding="UTF-8" %>
4. Eclipse 設置： Workspace > Text file encoding > Other > UTF-8 (徹底統一項目編碼)。
5. 上傳組件配置： 若用 Commons FileUpload / Servlet 3.0 @MultipartConfig，確保 request.setCharacterEncoding("UTF-8") 在 getPart() 前調用。

文件名落盤最佳實踐

• **不直接使用原始文件名**：生成 UUID + 原始擴展名 String stored = UUID.randomUUID() + "." + ext;。
• **元數據表記錄原名**：數據庫存 original_name (VARCHAR, CHARSET utf8mb4)、stored_name、content_type、size。
• **下載時恢復原名**：response.setHeader("Content-Disposition", "attachment; filename=\"" + URLEncoder.encode(originalName, "UTF-8") + "\"");

避坑指南

• ❌ 依賴 new String(bytes, "ISO-8859-1") 手動轉碼 —— 容器已正確解碼，二次轉碼反而破壞。
• ❌ 忽略 pageEncoding —— 導致 JSP 編譯時按系統默認編碼 (GBK) 讀取源文件，中文常量亂碼。
• ✅ 全鏈路 UTF-8 + Filter 統一編碼 + UUID 存儲 + 元數據記錄，徹底根治中文文件名問題。

字符編碼問題本質是「約定不一致」，建立「UTF-8 全棧」標準，配合元數據解耦存儲，是文件上傳的專業交付標準。