Log4j 2迁移疑难：深入排查并解决旧版Log4j配置残留问题

本文探讨log4j 1到log4j 2迁移后，应用仍尝试加载`log4j.xml`并报错的问题。尽管已更新maven依赖、代码和配置，错误依然出现。核心原因是javaee应用的`web.xml`中遗留的log4j 1相关配置。通过识别并移除`web.xml`中指向`log4j.xml`的`context-param`和`log4jconfiglistener`，可以彻底解决此问题，确保log4j 2的正确初始化和运行。

引言

从Log4j 1.x版本迁移到Log4j 2.x是许多JavaEE项目为了性能提升、功能增强和安全修复而进行的必要升级。这个过程通常涉及更新Maven或Gradle依赖、替换log4j.xml为log4j2.xml、调整代码中的日志API（如果直接使用了Log4j 1的API）以及处理潜在的冲突依赖。然而，即使完成了所有这些显而易见的步骤，有时应用在启动时仍然会抛出与Log4j 1相关的警告或错误，提示它正在寻找旧的log4j.xml配置文件。这通常表明存在一些隐藏的遗留配置，阻碍了Log4j 2的正确加载。

问题现象与初步排查

在将一个Maven多模块JavaEE项目从Log4j 1.2.17迁移到Log4j 2.19.0后，开发者可能已经执行了以下操作：

1. 更新了所有pom.xml文件中的Log4j依赖，将其替换为Log4j 2的相应依赖（如log4j-api、log4j-core等）。
2. 将旧的log4j.xml配置文件更名为log4j2.xml，并根据Log4j 2的语法进行了更新。
3. 移除了Log4j 1相关的log4j.dtd文件。
4. 在其他可能引入Log4j 1的第三方依赖（如docx4j）中添加了排除项，以避免Log4j 1的传递性依赖。
5. 检查了项目代码，确保没有直接引用Log4j 1的API。

尽管进行了上述全面的清理，当启动Tomcat服务器时，仍然可能在控制台看到以下类似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风格的配置文件（log4j:configuration是Log4j 1的根元素），并且可能在寻找log4j.xml。此时，常规的搜索（如在项目代码、Tomcat配置甚至整个磁盘上搜索这些日志信息或log4j.xml）可能都无济于事，使得问题变得难以定位。

根源定位：Web应用部署描述符中的遗留配置

这类问题的根源往往在于一些不那么显眼，但对应用启动流程至关重要的配置，尤其是在JavaEE环境中。对于Web应用而言，web.xml（Web应用部署描述符）是一个常见的“藏污纳垢”之处。在Log4j 1时代，Spring框架为了方便集成Log4j，提供了特定的ContextListener和context-param来初始化Log4j。当迁移到Log4j 2时，这些旧的配置通常会被遗漏。

具体而言，web.xml中可能存在以下类似的配置片段：

    log4jConfigLocation
    classpath:log4j.xml



    log4jExposeWebAppRoot
    false



    org.springframework.web.util.Log4jConfigListener

这些配置的作用是：

码上飞

码上飞（CodeFlying） 是一款AI自动化开发平台，通过自然语言描述即可自动生成完整应用程序。

下载

• log4jConfigLocation和classpath:log4j.xml：明确告诉Web容器（例如Tomcat），Log4j的配置文件位于类路径下的log4j.xml。
• org.springframework.web.util.Log4jConfigListener：这是一个Log4j 1专用的监听器，由Spring框架提供，用于在Web应用启动时初始化Log4j 1日志系统，并读取上述log4jConfigLocation指定的配置文件。

即使项目代码中不再有Log4j 1的依赖，如果web.xml中仍然存在Log4jConfigListener，Web容器在启动时依然会尝试加载并实例化这个监听器。由于Log4jConfigListener是为Log4j 1设计的，它会按照Log4j 1的机制去寻找并解析log4j.xml。当找不到Log4j 1的API或配置文件格式不匹配时，就会抛出上述的警告和错误。

解决方案

解决此问题的关键在于识别并移除web.xml中所有与Log4j 1相关的配置。

1. 定位web.xml： 找到项目中的web.xml文件，通常位于src/main/webapp/WEB-INF/目录下。
2. 移除遗留配置： 删除web.xml中所有与log4jConfigLocation、log4jExposeWebAppRoot以及org.springframework.web.util.Log4jConfigListener相关的和标签。

修改后的web.xml将不再包含这些旧的Log4j 1初始化指令。Log4j 2拥有自己的初始化机制，它会自动在类路径下寻找log4j2.xml、log4j2.json、log4j2.yaml或log4j2.properties等配置文件进行加载。因此，移除这些旧配置并不会影响Log4j 2的正常运行，反而会清除干扰，使其能够正确初始化。

最佳实践与注意事项

为了避免类似问题，并确保Log4j 2迁移的顺利进行，建议遵循以下最佳实践：

• 彻底清理依赖： 确保所有pom.xml或build.gradle文件中都已移除Log4j 1的直接和传递性依赖。使用Maven的dependency:tree或Gradle的dependencies命令可以帮助检查。
• 全面审查配置文件： 除了web.xml，还应检查其他可能的配置文件，如application.xml、Spring配置文件（如果Spring通过XML配置Log4j）等，确保没有遗留的Log4j 1相关配置。
• 理解Log4j 2的初始化机制： Log4j 2通常无需显式配置监听器来初始化。它会通过其内部的Log4jContextFactory自动查找并加载类路径下的配置文件。
• 搜索关键词： 在整个项目（包括配置文件、源代码和资源文件）中搜索log4j.xml、Log4jConfigListener、log4jConfigLocation等关键词，以确保没有遗漏。
• 测试验证： 迁移完成后，务必进行全面的集成测试和系统测试，确保日志能够正常输出，且没有出现任何旧版日志框架的警告或错误。

总结

Log4j 1到Log4j 2的迁移是一个需要细致处理的过程。当遇到迁移后应用仍然尝试加载log4j.xml并抛出Log4j 1相关错误时，通常不是因为Log4j 2配置错误，而是因为Web应用部署描述符web.xml中遗留了Log4j 1的初始化配置。通过移除web.xml中指向log4j.xml的context-param和org.springframework.web.util.Log4jConfigListener，可以有效解决这一问题，确保Log4j 2能够独立且正确地初始化其日志系统。彻底的清理和对配置细节的关注是成功迁移的关键。