Maven Shade 插件会覆盖 Log4J2 所需的关键资源（如 Log4j2Plugins.dat 和 META-INF/services/），导致动态注册的 Appender 无法被识别和触发；正确配置资源合并策略或改用 spring-boot-maven-plugin 即可彻底解决。
maven shade 插件会覆盖 log4j2 所需的关键资源（如 `log4j2plugins.dat` 和 `meta-inf/services/`），导致动态注册的 appender 无法被识别和触发；正确配置资源合并策略或改用 `spring-boot-maven-plugin` 即可彻底解决。
当通过 maven-shade-plugin 构建 Uber JAR 时，Log4J2 的插件发现机制常常失效——即使你已通过 Configuration.addAppender() 成功注册了自定义 Appender，它依然不会接收日志事件。根本原因在于：Shade 插件默认采用“覆盖式”合并策略，而 Log4J2 依赖多个 JAR 中分散的关键元数据文件协同工作，这些文件一旦丢失或未正确合并，插件扫描即告失败。
? 关键资源及其作用
- META-INF/org/apache/logging/log4j/core/config/plugins/Log4j2Plugins.dat：Log4J2 插件缓存文件，由 log4j-core 编译期生成，用于加速插件类加载。多个模块（如自定义 Layout、Appender）若各自提供该文件，必须合并而非覆盖。
- META-INF/services/org.apache.logging.log4j.core.appender.Appender 等服务文件：遵循 Java SPI 规范，声明可加载的组件实现。缺失将导致 ServiceLoader 无法发现扩展类。
- META-INF/MANIFEST.MF 中的 Multi-Release: true：启用多版本 JAR 支持，确保 JDK 11+ 下 StackTraceElement 解析等核心功能正常（Log4J2 在 log4j-core 中为不同 JDK 版本提供了 META-INF/versions/9/ 等兼容类）。
✅ 方案一：正确配置 maven-shade-plugin
需显式声明三类 Transformer，确保关键资源被安全合并：
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>3.4.1</version>
<dependencies>
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-transform-maven-shade-plugin-extensions</artifactId>
<version>0.1.0</version>
</dependency>
</dependencies>
<configuration>
<transformers>
<!-- 合并所有 Log4j2Plugins.dat 文件 -->
<transformer implementation="org.apache.logging.log4j.maven.plugins.shade.transformer.Log4j2PluginCacheFileTransformer"/>
<!-- 合并 META-INF/services/ 下所有 SPI 文件 -->
<transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
<!-- 保留并增强 MANIFEST，标记为 Multi-Release JAR -->
<transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
<manifestEntries>
<Multi-Release>true</Multi-Release>
</manifestEntries>
</transformer>
</transformers>
</configuration>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
</execution>
</executions>
</plugin>⚠️ 注意：log4j-transform-maven-shade-plugin-extensions 是 Apache 官方维护的专用扩展（GitHub 地址），务必引入，否则 Log4j2PluginCacheFileTransformer 不可用。
✅ 方案二（推荐）：改用 spring-boot-maven-plugin
即使项目不使用 Spring Boot 框架，该插件也极适合构建可执行 JAR——它采用“嵌套 JAR”结构（BOOT-INF/lib/），完整保留原始依赖 JAR 的 META-INF，从根本上规避资源冲突：
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<version>2.7.18</version> <!-- Java 8 兼容 -->
<executions>
<execution>
<goals>
<goal>repackage</goal>
</goals>
</execution>
</executions>
</plugin>构建后，运行 java -jar target/your-app.jar 即可，Log4J2 动态 Appender 将 100% 正常工作。其底层依赖轻量级 spring-boot-loader（仅约 200KB），无任何 Spring 框架侵入性。
? 验证与调试建议
- 检查生成的 JAR 是否包含 META-INF/org/apache/logging/log4j/core/config/plugins/Log4j2Plugins.dat（且内容含你的 Appender 类名）；
- 运行时添加 JVM 参数 -Dlog4j2.debug=true，观察控制台是否输出 Found plugin 及你的 Appender 类；
- 避免手动解压/重打包 Log4J2 JAR（如问题中 Scenario 4），此操作必然破坏 META-INF 结构。
综上，Log4J2 与 Shade 的兼容性问题本质是资源合并策略失配。优先选用 spring-boot-maven-plugin 获得开箱即用的可靠性；若必须使用 Shade，请严格按官方扩展配置 Transformer——二者皆能确保动态 Appender 在 Fat JAR 中稳定生效。
