Spring MVC 整合 FreeMarker 解決中文亂碼的最佳配置

Spring MVC 整合 FreeMarker 解決中文亂碼的最佳配置

在 Spring MVC 中使用 FreeMarker 視圖時，若響應編碼未正確設置，頁面極易出現中文亂碼。核心解決點在於 FreeMarkerViewResolver 的 contentType 屬性。

關鍵配置

<bean id="freemarkerConfig" class="org.springframework.web.servlet.view.freemarker.FreeMarkerConfigurer">
    <property name="templateLoaderPath" value="/WEB-INF/freemarker"/>
</bean>

<bean id="viewResolver" class="org.springframework.web.servlet.view.freemarker.FreeMarkerViewResolver">
    <!-- 核心：強制響應 Content-Type 帶上 charset=UTF-8 -->
    <property name="contentType" value="text/html;charset=UTF-8"/>
    <property name="cache" value="true"/>
    <property name="prefix" value=""/>
    <property name="suffix" value=".ftl"/>
    <property name="order" value="0"/>
</bean>

為什麼這樣配置有效？

• FreeMarkerViewResolver 在渲染視圖前會調用 response.setContentType(contentType)。
• 默認 contentType 為 text/html，缺少 charset，瀏覽器按系統默認編碼（如 GBK）解析，導致 UTF-8 模板輸出亂碼。
• 顯式設置 text/html;charset=UTF-8 後，瀏覽器明確按 UTF-8 解碼，亂碼消失。

雙重保障：模板頁面也要聲明編碼

在每個 .ftl 頁面頭部添加：

<#ftl encoding="UTF-8">
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    ...

確保模板文件本身以 UTF-8 保存（IDE 設置 File Encodings = UTF-8），瀏覽器端也聲明 UTF-8，三方一致，徹底杜絕亂碼。

常見誤區

1. 只在 web.xml 配置 CharacterEncodingFilter：該過濾器只處理請求參數編碼，不影響響應輸出編碼。
2. 在 Controller 中 response.setCharacterEncoding("UTF-8")：若在視圖解析器渲染前調用可能被覆蓋，不如在 ViewResolver 統一配置可靠。