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` 可彻底解决该问题。
Log4J2 的插件机制高度依赖类路径下的元数据文件，尤其是 META-INF/org/apache/logging/log4j/core/config/plugins/Log4j2Plugins.dat（缓存插件签名）和 META-INF/services/ 下的服务发现文件（如 org.apache.logging.log4j.core.appender.Appender）。当使用 maven-shade-plugin 构建 Uber JAR 时，若未显式声明资源合并策略，Shade 会静默丢弃重复路径的资源——例如多个依赖 JAR 中都存在 Log4j2Plugins.dat，默认仅保留最后一个（通常是 log4j-core 自带的原始文件），而你自定义 Appender 所属模块生成的插件元数据则被完全丢失。这正是动态 Appender 在 IDE 中正常、但在 Fat Jar 中“静默失效”的根本原因。
✅ 正确配置 maven-shade-plugin（推荐用于非 Spring 项目）
需启用三类关键 Transformer，确保插件元数据、服务文件与多版本支持完整合并：
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>3.4.1</version>
<dependencies>
<!-- 提供 Log4J2 专用合并逻辑 -->
<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/ 下的服务提供者配置 -->
<transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
<!-- 保留并增强 MANIFEST.MF，标记为 Multi-Release JAR（JDK 11+ 兼容） -->
<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 官方维护的扩展，必须显式声明为 dependency，否则 Log4j2PluginCacheFileTransformer 类将不可用；
- 若项目含多个 Log4J2 扩展模块（如自定义 Layout、Appender、Lookup），所有模块的 Log4j2Plugins.dat 都会被自动合并；
- Multi-Release: true 不仅支持 JDK 11+ 的 Caller Stack Walker 优化，也是 Log4J2 2.17+ 版本在高版本 JDK 上稳定运行的前提。
✅ 更优替代方案：使用 spring-boot-maven-plugin（无 Spring 依赖也可用）
该插件采用“嵌套 JAR”结构（而非解压合并），天然保留所有原始 JAR 的 META-INF 完整性，且零配置兼容 Log4J2：
<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>打包后生成的可执行 JAR 内部结构为：
BOOT-INF/lib/log4j-core-2.17.2.jar ← 原始 JAR，META-INF 完整保留 BOOT-INF/lib/your-custom-appender.jar ← 同样完整 org/springframework/boot/loader/JarLauncher.class
此方式无需任何 Transformer 配置，彻底规避资源冲突风险，且启动性能优于传统 Shade（类加载按需解压）。即使项目不使用 Spring 框架，也只需引入轻量级 spring-boot-loader（~200KB），无其他运行时依赖。
总结
| 方案 | 适用场景 | 关键优势 | 风险提示 |
|---|---|---|---|
| Shade + Transformers | 必须使用 Shade 的遗留构建体系 | 控制粒度高，单 JAR 部署简洁 | 配置易遗漏，Log4j2Plugins.dat 合并失败即导致 Appender 不可见 |
| spring-boot-maven-plugin | 新项目 / 追求稳定性与兼容性 | 零配置兼容 Log4J2，天然支持多版本 JDK，结构清晰 | 输出 JAR 略大（含 loader），但可通过 excludeDevtools 等优化 |
无论选择哪种方案，请务必验证最终 JAR 中是否存在 BOOT-INF/lib/（Spring Boot）或 META-INF/org/apache/logging/log4j/core/config/plugins/Log4j2Plugins.dat（Shade），并确认你的自定义 Appender 类名已出现在该文件内——这是动态注册生效的最终依据。
