迁移Apache Velocity时遭遇编码渲染问题求助

1. 明确指定Velocity输出编码 #

新版Velocity默认输出编码可能不再继承输入编码，需显式配置：
在Velocity配置文件中添加：

output.encoding = UTF-8

同时在VelocityServlet的doRequest方法里强制设置响应编码：

response.setContentType("text/html; charset=UTF-8");

即便Tomcat全局配置了UTF-8，Velocity输出流若未绑定响应编码，仍会出现转码错误。

2. 确认模板文件的实际编码 #

检查所有.vm模板是否以UTF-8无BOM格式保存。部分编辑器默认保存带BOM的UTF-8，或误存为GBK/ISO-8859-1，会导致Velocity读取模板时解析异常。可通过Notepad++等工具查看并转换编码格式。

3. 配置WebappResourceLoader的编码 #

补充资源加载器的编码参数到Velocity配置文件：

resource.loader.webapp.encoding = UTF-8

新版Velocity的资源加载器需明确指定读取模板的编码，避免依赖系统默认编码。

4. 修正外部JS的加载逻辑 #

外部JS出现éà èù这类乱码，说明内容在渲染或传输中被二次转码：

• 确保JS文件本身为UTF-8编码
• 模板中引用JS时用静态方式并指定编码：

  <script src="/js/your-script.js" charset="UTF-8"></script>
  

  若JS是Velocity动态生成的，需同步确保生成时的输出编码为UTF-8，且响应头设置正确。

5. 验证Velocity运行时编码参数 #

在Servlet中添加调试代码，确认关键编码配置生效：

System.out.println("Input Encoding: " + getVelocityEngine().getProperty(RuntimeConstants.INPUT_ENCODING));
System.out.println("Output Encoding: " + getVelocityEngine().getProperty(RuntimeConstants.OUTPUT_ENCODING));
System.out.println("Resource Loader Encoding: " + getVelocityEngine().getProperty("resource.loader.webapp.encoding"));

确保所有输出值均为UTF-8，排除配置未生效的情况。

内容的提问来源于stack exchange，提问作者Dominique Sauquet