将自定义Log4j2 Lookup类打包为Jar部署到Tomcat后失效问题排查

API 探路者

2026-8-20

问题原因

核心问题是Log4j2的插件扫描机制：当自定义MyLookup打包成Jar放在WEB-INF/lib时，Log4j2没有识别到这个插件，导致无法解析${headerlookup:header}占位符。

Log4j2默认通过插件元数据文件（META-INF/org/apache/logging/log4j/core/config/plugins/Log4j2Plugins.dat）发现插件。把类放在WEB-INF/classes时，编译阶段的注解处理器会自动生成这个元数据文件到classes目录，Log4j2启动时能扫描到；但打包成Jar时如果没包含这个元数据文件，Log4j2就找不到你的自定义Lookup插件。

解决方法

方法1：打包Jar时生成插件元数据

如果用Maven构建，添加Log4j2的插件处理器依赖，让编译阶段自动生成插件元数据：

<dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-plugin-processor</artifactId>
    <version>与你的Log4j2版本一致</version>
    <scope>provided</scope>
</dependency>

重新打包Jar后，Jar内部会包含Log4j2Plugins.dat文件，Log4j2启动时就能识别到headerlookup插件。

方法2：在Log4j2配置中手动注册插件

修改log4j2.xml，在<Configuration>节点下手动指定插件类，跳过元数据扫描：

<Configuration>
    <!-- 手动注册自定义Lookup插件 -->
    <Plugins>
        <Plugin type="StrLookup" name="headerlookup" class="你的MyLookup类全限定名"/>
    </Plugins>

    <RollingFile name="Appender">
        <FileName>file.xml</FileName>
        <PatternLayout header="${headerlookup:header}">
            <Pattern>%msg</Pattern>
        </PatternLayout>
        <Policies>
            <SizeBasedTriggeringPolicy size="6MB" />
        </Policies>
    </RollingFile>
</Configuration>

这种方式无需依赖元数据文件，Log4j2会直接加载指定的类作为Lookup插件。