如何在Log4j2配置中通过xi:include引用Maven依赖中的外部配置文件

问题分析 #

你遇到的错误核心是Log4j2在当前项目的classpath根目录找不到log4j2-include.xml——因为这个文件是在你引入的Maven依赖jar包内部，而非当前项目的资源目录下。直接写文件名会让解析器在本地项目编译后的target/classes下查找，自然找不到依赖jar里的文件。

正确配置方式 #

要引用依赖jar包中的资源，需要使用classpath:协议来指定路径，让Log4j2从整个类路径（包括所有依赖jar）中查找文件。修改你的log4j2.xml配置如下：

<?xml version="1.0" encoding="UTF-8"?>
<configuration status="WARN" xmlns:xi="http://www.w3.org/2001/XInclude">
  <Properties>
    <Property name="logger.app" value="${spring:appName:-UNDEFINED}"/>
    <Property name="logger.appVersion" value="${spring:appVersion:-UNDEFINED}"/>
  </Properties>
  <!-- 使用classpath协议引用依赖中的配置文件 -->
  <xi:include href="classpath:log4j2-include.xml">
    <!-- 可选：添加fallback避免解析失败直接崩溃 -->
    <xi:fallback>
      <Appenders>
        <Console name="Console" target="SYSTEM_OUT">
          <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
        </Console>
      </Appenders>
      <Loggers>
        <Root level="info">
          <AppenderRef ref="Console"/>
        </Root>
      </Loggers>
    </xi:fallback>
  </xi:include>
</configuration>

关键细节说明 #

• classpath:协议：这是Java类路径资源的标准引用方式，会遍历所有已加载的jar包和项目classpath目录查找目标文件。
• 文件路径准确性：如果log4j2-include.xml在依赖jar的某个子包下（比如com/example/config/），需要写完整路径：classpath:com/example/config/log4j2-include.xml。
• fallback元素：添加<xi:fallback>可以在引用失败时提供默认配置，避免出现你遇到的“Fatal Error”导致日志系统完全无法启动。

验证步骤 #

• 检查你的Maven依赖是否正确引入，执行mvn dependency:tree确认logging:logging-libs:1.0.1已被包含。
• 解压依赖jar包（可以用IDE直接查看），确认log4j2-include.xml确实存在于jar的对应路径下。
• 重新编译项目，启动应用时观察日志，确认配置加载成功。

内容的提问来源于stack exchange，提问作者Natalia Sizykh