升级至Struts 6.0.0搭配Struts2 jQuery插件4.0.3时遇FreeMarker模板错误

问题根源 #

Struts 6.0.0升级后，FreeMarker默认开启了HTML自动转义，而你使用的Struts2 jQuery plugin 4.0.3版本的模板（如div.ftl）仍在使用?html这种手动转义语法，两者冲突触发解析错误：

Using ?html (legacy escaping) is not allowed when auto-escaping is on with a markup output format (HTML), to avoid double-escaping mistakes.

解决方案 #

方案1：升级Struts2 jQuery插件（推荐） #

4.0.3版本不兼容Struts6，直接升级到支持Struts6的最新版本（如4.1.3及以上），新版本已经修复了模板中的转义语法冲突问题，适配了Struts6的FreeMarker配置。

方案2：临时绕过（无法升级插件时） #

方法A：修改FreeMarker配置

在struts.xml中添加以下配置，禁用旧转义语法的限制：

<constant name="struts.freemarker.settings.legacy_escape_disabled" value="false" />

该配置允许在自动转义开启时使用?html语法，避免解析报错。

方法B：手动修复模板文件

1. 从插件中复制template/jquery/div.ftl文件到项目的src/main/resources/template/jquery/目录下
2. 修改第22行代码，移除?html：

   <#if parameters.id??> id="${parameters.id}"<#rt/></#if>
   

   因为Struts6的FreeMarker已经自动处理HTML转义，无需手动添加?html，避免双重转义。

方法C：全局关闭HTML自动转义（不推荐）

在struts.xml中添加配置：

<constant name="struts.freemarker.settings.output_format" value="TEXT" />

此方法会全局关闭HTML自动转义，可能引入XSS安全风险，仅作为临时应急方案。

内容的提问来源于stack exchange，提问作者Alireza Fattahi