Tomcat中JSP引入UTF-8编码HTML文件失效问题排查

核心原因 #

<%@ include %>属于静态包含，Tomcat在编译JSP时会直接读取被包含的index.html文件内容并合并到JSP源码中，但Tomcat默认会用系统平台的默认编码（比如Windows下的GBK）去读取这个HTML文件——哪怕文件本身是UTF-8编码，也会在读取阶段就出现乱码，最终渲染到页面自然显示异常。

为什么其他场景正常？ #

• 直接访问index.html时，浏览器能通过文件内的<meta charset="UTF-8">标签识别编码，正确解析内容；
• 不含静态包含的JSP页面正常，是因为你大概率已经在JSP头部设置了pageEncoding="UTF-8"，Tomcat会用这个编码读取JSP文件；
• WebSocket传输的字符是在内存中直接处理编码逻辑，和文件读取阶段的编码设置无关，所以不受影响。

之前的配置为什么无效？ #

• SetCharacterEncodingFilter和Connector的URIEncoding="UTF-8"都是处理HTTP请求/响应阶段的编码，而静态包含的文件编码问题出在Tomcat编译JSP的文件读取阶段，这些配置覆盖不到这个环节；
• 添加jsp-config后JS文件报错，大概率是你配置的编码规则（比如<page-encoding>）被Tomcat误应用到了JS文件上，把JS当成JSP解析，导致语法报错。

可行的解决方法 #

• 方法1：在包含HTML的JSP中明确编码
  在JSP页面顶部添加以下声明，pageEncoding会指定Tomcat读取当前JSP及所有静态包含文件时使用UTF-8：

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

• 方法2：修改Tomcat全局JSP读取编码（不推荐，影响所有项目）
  打开Tomcat的conf/web.xml，找到jsp对应的servlet配置，添加fileEncoding初始化参数：

  <servlet>
      <servlet-name>jsp</servlet-name>
      <servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>
      <init-param>
          <param-name>fileEncoding</param-name>
          <param-value>UTF-8</param-value>
      </init-param>
      <!-- 保留原有其他配置 -->
  </servlet>
  

  这个配置会让Tomcat处理所有JSP及静态包含文件时默认用UTF-8读取，但会影响服务器上的所有项目，仅适合全局统一编码的场景。

• 方法3：确保HTML文件是UTF-8无BOM格式
  部分编辑器保存UTF-8文件时会添加BOM头，Tomcat读取时可能解析出乱码字符。用Notepad++等工具将index.html转换为UTF-8 无BOM格式再测试。

内容的提问来源于stack exchange，提问作者Martin Gisser