解決 JSP include 動態引用亂碼問題：雙重編碼宣告法

解決 JSP include 動態引用亂碼問題：雙重編碼宣告法

使用 <jsp:include> 動態引用 JSP 頁面時，常遇到引用頁面出現亂碼的問題。本文記錄排查過程與最終解決方案：在主頁面與被引用頁面雙雙宣告 UTF-8 編碼。

一、問題現象

主頁面使用 <jsp:include page="fragment.jsp" /> 引用動態片段，結果片段區域顯示亂碼（如下圖左側 iframe 區域）。

二、初步嘗試：單側宣告編碼

網路常見建議：在被引用的 JSP 檔案頂部加入 page 指令：

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

結果：問題未解決。

三、根因分析

<jsp:include> 屬於動態引用，容器會分別編譯主頁面與被引用頁面為獨立 Servlet，再於執行期合併輸出流。若主頁面未宣告編碼，容器預設可能使用 ISO-8859-1 輸出，導致合併時編碼不一致產生亂碼。

單純在被引用頁面宣告無法改變主頁面的輸出編碼設定。

四、解決方案：雙重宣告

在主頁面與被引用頁面的第一行同時加入：

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

主頁面（引用端）

被引用頁面（片段端）

五、原理補充

• contentType="text/html; charset=UTF-8"：設定 HTTP 回應標頭 Content-Type，告訴瀏覽器以 UTF-8 解碼。
• pageEncoding="UTF-8"：指定 JSP 檔案本身的儲存編碼，容器讀取原始碼時依此解碼。
• 兩者缺一不可，且必須放在檔案第一行，避免輸出緩衝區已提交導致設定無效。

六、最佳實踐建議

1. 專案層級統一：在 web.xml 配置 <jsp-config> 統一指定編碼，避免逐頁重複宣告。
2. IDE 設定：確保專案編碼、檔案儲存編碼、Tomcat URIEncoding 均為 UTF-8。
3. 靜態引用 <%@ include file="" %> 不會有此問題（編譯期合併），但無法傳遞動態參數。