Log4j 1到Log4j 2迁移后仍旧引用旧配置的排查与解决

在将javaee项目从log4j 1迁移到log4j 2时，即使更新了依赖、配置文件和代码，项目仍可能因残留的log4j 1配置而报错。本文将深入探讨此类问题的常见原因，特别是`web.xml`中遗留的log4j 1相关配置，并提供详细的排查步骤和解决方案，旨在帮助开发者彻底清除旧配置，确保log4j 2平稳运行，避免因配置冲突导致的日志系统异常。

Log4j 1到Log4j 2迁移概述

Log4j 2相较于Log4j 1在性能、功能和灵活性上都有显著提升。迁移通常涉及以下几个核心步骤：

1. 更新Maven/Gradle依赖：移除所有Log4j 1相关的依赖（如log4j:log4j），并引入Log4j 2的核心依赖（org.apache.logging.log4j:log4j-api和org.apache.logging.log4j:log4j-core）。
2. 排除传递性依赖：检查项目中其他库（如docx4j、Spring旧版本等）是否间接引入了Log4j 1，并通过Maven的标签或Gradle的exclude规则将其排除。
3. 更新配置文件：将log4j.xml、log4j.properties等Log4j 1配置文件替换为log4j2.xml、log4j2.properties或log4j2.json，并根据Log4j 2的语法进行配置。
4. 代码适配：如果代码中直接使用了Log4j 1的API，需要更新为Log4j 2的API。若希望保持Log4j 1 API兼容性，可引入Log4j 2的Log4j 1 API桥接器（org.apache.logging.log4j:log4j-1.2-api）。
5. 清理旧文件：删除旧的Log4j 1相关的DTD文件或配置文件。

迁移陷阱：残留的Log4j 1配置

即使完成了上述所有步骤，在某些JavaEE项目中，尤其是在使用Spring框架的传统Web应用中，仍可能遇到Log4j 1相关的错误日志，例如：

log4j:WARN Continuable parsing error 2 and column 31
log4j:WARN L'élément racine de document "Configuration" doit correspondre à la racine DOCTYPE "null".
log4j:WARN Continuable parsing error 2 and column 31
log4j:WARN Le document nest pas valide : aucune grammaire détectée.
log4j:ERROR DOM element is - not a  element.

这些错误信息明确指出Log4j 1的XML解析器正在尝试解析一个不符合其DTD的配置，甚至可能尝试将Log4j 2的配置文件（如log4j2.xml）误认为是Log4j 1的配置。这通常意味着某个地方仍在显式或隐式地加载Log4j 1的配置机制。

深入排查：定位旧配置源头

当Log4j 1的错误信息持续出现时，需要进行更深入的排查：

1. 检查所有pom.xml文件：确保所有模块的pom.xml都已正确排除Log4j 1依赖，并且没有其他传递性依赖引入。
2. 全局文件搜索：在整个项目工作区甚至服务器配置目录中，搜索log4j.xml、log4j.properties、Log4jConfigListener等关键字，以排除任何隐藏的旧配置文件或配置引用。
3. 检查应用服务器配置：对于Tomcat等Servlet容器，检查其context.xml或其他配置文件中是否有Log4j相关的配置。

解决方案：移除web.xml中的Log4j 1配置

在许多JavaEE或Spring Web应用中，web.xml是一个容易被忽视的关键点。Spring框架在早期版本中提供了Log4jConfigListener来集成Log4j 1，并通过context-param指定Log4j 1配置文件的位置。如果这些配置在迁移到Log4j 2后未被移除，Web容器启动时仍会尝试加载Log4j 1的日志系统。

以下是典型的web.xml中可能存在的Log4j 1相关配置：

Tago AI

AI生成带货视频，专为电商卖货而生

下载

    log4jConfigLocation
    classpath:log4j.xml



    log4jExposeWebAppRoot
    false



    org.springframework.web.util.Log4jConfigListener

• log4jConfigLocation: 这个参数明确指示Web容器去类路径下寻找名为log4j.xml的Log4j 1配置文件。
• log4jExposeWebAppRoot: 这是Log4j 1的一个辅助配置，用于决定是否将Web应用根目录暴露给Log4j。
• org.springframework.web.util.Log4jConfigListener: 这是Spring框架提供的Log4j 1集成监听器，它会在Web应用启动时初始化Log4j 1日志系统。

解决办法：

将上述所有Log4j 1相关的和配置从web.xml中彻底删除。在Log4j 2时代，尤其是在Spring Boot项目中，通常不需要在web.xml中显式配置日志监听器，Log4j 2会通过其自身的查找机制（如在classpath下查找log4j2.xml）或通过Spring Boot的自动配置来初始化。

删除这些配置后，重新部署并启动应用，Log4j 1的错误信息应该会消失，并且Log4j 2会按照log4j2.xml或其他Log4j 2配置文件正常工作。

迁移注意事项与最佳实践

1. 彻底清理依赖：使用Maven或Gradle的依赖树分析工具（如mvn dependency:tree或gradle dependencies）来检查所有模块的运行时依赖，确保没有Log4j 1的残留。
2. Log4j 2配置文件的命名与位置：Log4j 2默认会按特定顺序在classpath下查找配置文件，例如log4j2.xml、log4j2.json、log4j2.properties。确保你的Log4j 2配置文件命名正确且放置在classpath可访问的位置。
3. Log4j 2桥接器：如果项目中存在大量遗留代码仍使用Log4j 1的API（如org.apache.log4j.Logger），可以引入Log4j 2的Log4j 1 API桥接器(log4j-1.2-api)。这允许旧代码无需修改即可将日志路由到Log4j 2。
4. Spring Boot集成：对于Spring Boot项目，Log4j 2的集成通常更加简单，只需引入spring-boot-starter-log4j2依赖并排除默认的spring-boot-starter-logging即可。Spring Boot会自动配置Log4j 2。
5. 测试验证：迁移完成后，务必运行全面的测试，确保日志输出符合预期，没有丢失或格式错误的情况。

总结

将项目从Log4j 1迁移到Log4j 2是一个涉及多方面的任务。除了更新依赖、配置文件和代码，对web.xml等部署描述符的彻底检查同样至关重要。残留的Log4j 1配置，特别是Log4jConfigListener和相关的context-param，是导致迁移后仍出现Log4j 1错误日志的常见原因。通过系统性的排查和清理，可以确保Log4j 2在项目中平稳、高效地运行。