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

本文探讨了从log4j 1迁移至log4j 2后，应用仍尝试加载log4j 1配置文件的常见问题。即使表面上已移除所有log4j 1依赖和配置文件，旧的spring框架集成配置（如`web.xml`中的`log4jconfiglocation`上下文参数和`log4jconfiglistener`）仍可能导致冲突。教程将指导开发者如何识别并移除这些遗留配置，确保log4j 2的正确初始化和运行，避免不必要的警告和错误，从而顺利完成日志框架升级。

理解Log4j 1到Log4j 2迁移的挑战

将JavaEE项目从Log4j 1.x升级到Log4j 2.x是现代应用开发中的常见需求，这通常是为了获得更好的性能、更丰富的功能集以及解决Log4j 1.x版本中存在的安全漏洞。然而，这一迁移过程并非总是一帆风顺，尤其是在大型、多模块或历史悠久的项目中。开发者通常会采取以下步骤：

1. 更新项目依赖： 在pom.xml（Maven）或build.gradle（Gradle）中移除Log4j 1.x的依赖，并引入Log4j 2.x的核心、API和实现（如log4j-api、log4j-core）。
2. 配置迁移： 将旧的log4j.xml或log4j.properties配置文件替换为Log4j 2兼容的log4j2.xml、log4j2.json或log4j2.properties。
3. 代码适配： 更新任何直接使用Log4j 1.x API的代码，使其适配Log4j 2.x API（尽管Log4j 2提供了兼容层，但直接使用其API是最佳实践）。
4. 排除传递性依赖： 仔细检查项目的传递性依赖，确保没有其他库意外地重新引入Log4j 1.x。这通常通过在pom.xml中使用标签实现。

尽管完成了上述所有步骤，有时应用在启动时仍会抛出与Log4j 1.x相关的警告或错误，这表明系统中某个部分仍在尝试加载或初始化Log4j 1.x的配置。

识别Log4j 1配置残留的症状

当Log4j 2迁移不彻底，Log4j 1的配置残留仍在发挥作用时，通常会在应用服务器（如Tomcat）启动日志中观察到以下类型的警告或错误：

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.x内部解析器发出的。具体来说：

• log4j:WARN Continuable parsing error 和 log4j:WARN Le document nest pas valide : aucune grammaire détectée. 表明Log4j 1的XML解析器在尝试处理一个它不认识的XML文件（可能是Log4j 2的log4j2.xml，或者是一个不符合Log4j 1 DTD的XML）。
• log4j:ERROR DOM element is - not a element. 则直接指出，Log4j 1的配置解析器期望找到一个以作为根元素的配置文件，但它没有找到或者找到的根元素不匹配。

这些症状明确指示，尽管您已将Log4j 2配置到位，但某个机制仍在激活Log4j 1的初始化流程。

深入排查：查找隐藏的Log4j 1配置

要彻底解决这个问题，需要系统地排查项目中可能隐藏Log4j 1配置的地方。

1. 检查项目依赖树

首先，确认项目中没有意外引入Log4j 1的运行时依赖。对于Maven项目，可以使用以下命令：

mvn dependency:tree | grep log4j

仔细检查输出，确保log4j:log4j（Log4j 1的核心库）没有作为任何模块的直接或传递性依赖被引入。如果发现，应在相应的pom.xml中添加来排除它。

2. 检查Web应用部署描述符（web.xml）

在JavaEE应用中，web.xml是配置Web组件和上下文参数的核心文件。在早期Spring版本（如Spring 1.x或2.x）中，为了方便集成Log4j 1，Spring提供了一个Log4jConfigListener，它通过context-param来指定Log4j 1配置文件的位置。这正是本问题中最常见的隐蔽原因。

请检查您的web.xml文件，查找类似以下内容的配置：

MakeSong

AI音乐生成，生成高质量音乐，仅需30秒的时间

下载

    log4jConfigLocation
    classpath:log4j.xml



    log4jExposeWebAppRoot
    false



    org.springframework.web.util.Log4jConfigListener

解释：

• log4jConfigLocation：这是一个上下文参数，用于指定Log4j 1配置文件的位置。classpath:log4j.xml意味着它会尝试在类路径下查找名为log4j.xml的文件。
• Log4jConfigListener：这是Spring框架提供的一个ServletContextListener，它在Web应用启动时负责初始化Log4j 1。它会读取log4jConfigLocation参数来加载Log4j 1的配置文件。

这些配置是为Log4j 1设计的，在迁移到Log4j 2后已不再需要。Log4j 2通常通过其自身的初始化机制（例如，在类路径中查找log4j2.xml）来完成配置，无需Spring的特定监听器。如果这些旧的配置仍然存在，Log4jConfigListener会在应用启动时被激活，并尝试使用Log4j 1的解析器去查找并解析log4j.xml，从而导致上述警告和错误。

3. 全局搜索与IDE支持

除了上述特定位置，还可以利用IDE的全局搜索功能，在整个项目（包括依赖库的源代码，如果可行）中搜索以下关键词：

• log4j.xml
• log4j:configuration
• Log4jConfigListener
• log4jConfigLocation
• org.apache.log4j (检查是否有代码直接引用了Log4j 1的类)

同时，检查应用服务器（如Tomcat）的conf目录下的server.xml、context.xml或任何自定义的JNDI配置，以防其中包含对Log4j 1配置的引用。

解决问题与验证

一旦确定了web.xml中的遗留配置是问题的根源，解决方案就非常直接。

1. 移除遗留配置

从您的web.xml文件中，彻底移除所有与log4jConfigLocation上下文参数、log4jExposeWebAppRoot上下文参数以及org.springframework.web.util.Log4jConfigListener监听器相关的条目。

示例： 假设您的web.xml中包含上述Log4j 1相关的配置，您应该删除以下部分：

    log4jConfigLocation
    classpath:log4j.xml



    log4jExposeWebAppRoot
    false




    org.springframework.web.util.Log4jConfigListener

2. 清理与重建

在修改web.xml后，务必执行以下步骤：

• 清理项目： 在IDE中执行Clean操作，或使用Maven命令mvn clean。
• 重新构建项目： 确保所有更改都已编译并打包到WAR/EAR文件中。
• 重新部署应用： 将更新后的WAR/EAR文件部署到应用服务器。
• 重启应用服务器： 彻底重启Tomcat或其他应用服务器。

3. 验证解决方案

重启服务器后，仔细检查Tomcat的控制台输出或日志文件。如果问题已解决，您将不再看到任何Log4j 1相关的WARN或ERROR信息，Log4j 2将按照您的log4j2.xml配置正常初始化和运行。

注意事项与最佳实践

• 彻底性： 迁移日志框架时，务必确保所有与旧版本相关的配置和依赖都被彻底清除。
• 传递性依赖： 始终警惕传递性依赖可能带来的旧版本库冲突。mvn dependency:tree是您的好帮手。
• Spring Boot项目： 对于Spring Boot项目，日志配置通常由Spring Boot Starter统一管理，并且不涉及web.xml。这类项目遇到此问题的情况较少，但仍需检查是否引入了不必要的传统Log4j 1依赖。
• 应用服务器特定配置： 某些应用服务器可能在其自身配置中包含日志框架的设置。在迁移时，也应检查这些配置，确保它们不会干扰或覆盖您的应用级Log4j 2配置。
• 测试： 迁移完成后，务必进行全面的日志功能测试，确保所有日志都能正确输出到预期位置，并且日志级别、格式等都符合要求。

通过遵循这些排查步骤和最佳实践，可以有效解决Log4j 2迁移后仍受Log4j 1配置干扰的问题，确保日志框架的平稳升级和应用的稳定运行。