如何解决Tomcat在Debian上的乱码问题

Debian上Tomcat乱码排查与修复

一、先定位乱码来源

• 确认是哪一环节出现乱码：
  1. 系统/控制台输出（如 catalina.out 启动日志）；2) 访问日志/应用日志；3) HTTP请求参数或页面显示。
• 快速检查系统环境：
  • 查看系统 locale：locale，推荐为 zh_CN.UTF-8 或 en_US.UTF-8。
  • 查看当前语言环境：echo $LANG $LC_CTYPE。
• 检查 Tomcat 日志与页面：
  • 查看 catalina.out 与 localhost.*.log 是否中文正常。
  • 用 curl -v 或浏览器开发者工具查看响应头 Content-Type 是否包含 charset=UTF-8。
• 检查请求参数：表单或 URL 参数是否为 UTF-8 编码提交。

二、系统层设置

• 生成并启用 UTF-8 locale（Debian 10/11/12 通用）：
  • 生成 locale：sudo dpkg-reconfigure locales，勾选 zh_CN.UTF-8（或 en_US.UTF-8）。
  • 临时生效：export LANG=zh_CN.UTF-8（或 en_US.UTF-8）；永久生效写入 /etc/default/locale 或 /etc/profile：
    • 示例：echo 'LANG=zh_CN.UTF-8' | sudo tee /etc/default/locale
• 重新登录或重启系统后验证：locale。
• 说明：Tomcat 运行依赖系统 locale，若系统不是 UTF-8，JVM 与日志输出易出现中文乱码。

三、Tomcat层设置

• 设置 Connector 请求编码
  • 编辑 conf/server.xml，在 上添加 URIEncoding=“UTF-8”：

    <Connector port="8080" protocol="HTTP/1.1"
               connectionTimeout="20000"
               redirectPort="8443"
               URIEncoding="UTF-8" />
    

  • 作用：保证 GET 查询串与 POST 表单 URL 解码为 UTF-8。
• 设置 JVM 默认编码
  • 编辑 bin/catalina.sh，在 if [ -z "$LOGGING_MANAGER" ]; then 分支内追加：

    LOGGING_MANAGER="-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8"
    

  • 如通过服务启动，也可在 /etc/default/tomcat9（或相应环境文件）中设置：

    JAVA_OPTS="$JAVA_OPTS -Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8"
    

  • 作用：统一 JVM 默认字符集 与 文件/资源文件名编码，修复启动日志与控制台中文乱码。
• 配置日志输出编码
  • 编辑 conf/logging.properties：
    • 将 java.util.logging.ConsoleHandler.encoding 设为 UTF-8；
    • 将 1catalina.org.apache.juli.AsyncFileHandler.encoding 等文件日志的 encoding 设为 UTF-8。
  • 注意：不要将日志编码随意改为 GBK；应与系统/Terminal 编码一致（通常为 UTF-8）。
• 应用层编码（Filter 与页面）
  • 在 web.xml 配置字符编码过滤器（Tomcat 自带）：

    <filter>
      <filter-name>setCharacterEncodingFilter</filter-name>
      <filter-class>org.apache.catalina.filters.SetCharacterEncodingFilter</filter-class>
      <init-param>
        <param-name>encoding</param-name>
        <param-value>UTF-8</param-value>
      </init-param>
      <init-param>
        <param-name>forceEncoding</param-name>
        <param-value>true</param-value>
      </init-param>
    </filter>
    <filter-mapping>
      <filter-name>setCharacterEncodingFilter</filter-name>
      <url-pattern>/*</url-pattern>
    </filter-mapping>
    

  • 在 Servlet/JSP 中：
    • request.setCharacterEncoding("UTF-8")（在读取参数前调用）；
    • JSP 头部：<%@ page contentType="text/html; charset=UTF-8" %>；
    • HTML 头部：<meta charset="UTF-8">。
• 静态资源与文件读写
  • 确保源码、模板、静态文件以 UTF-8 保存；
  • 读取/写入文件时显式指定 UTF-8。

四、重启与验证

• 重启 Tomcat：
  • 服务方式：sudo systemctl restart tomcat9（或 tomcat）；
  • 前台调试：./bin/catalina.sh run（便于直接观察控制台输出）。
• 验证要点：
  • catalina.out 与 localhost.*.log 中文正常；
  • 页面 <meta charset="UTF-8"> 与响应头一致；
  • 表单提交中文参数不乱码；
  • 若仍异常，检查反向代理（如 Nginx）是否设置了正确的 charset，以及浏览器是否以 UTF-8 渲染。

五、常见坑与建议

• 不要混用编码：系统、JVM、日志、应用、反向代理与浏览器应统一为 UTF-8。
• 仅设置 URIEncoding 不足以解决所有问题，需同时设置 JVM 默认编码 与 日志编码。
• 若系统 locale 不是 UTF-8，先修复系统层，再调整 Tomcat。
• 修改配置后务必重启，并优先查看 catalina.out 的错误线索。
• 使用 curl -H "Accept-Charset: UTF-8" -v http://localhost:8080/your-app 辅助排查响应头与内容编码。