SpringBoot2.7.x将logback升级到1.3.x以上版本的全过程解析

SpringBoot2.7.x将logback升级到1.3.x以上版本的全过程解析

不少开发者在尝试将SpringBoot 2.7.x项目中的Logback升级到1.3.x或更高版本时，都会遇到一个典型的启动报错。这背后的原因其实很明确：SpringBoot 2.7.x默认依赖的是logback-classic-1.2.x及以下版本，而到了1.3.x版本，Logback团队移除了一个关键类org.slf4j.impl.StaticLoggerBinder，这个类恰恰是SpringBoot启动时所依赖的。版本不匹配，冲突自然就来了。

一、报错原因分析

要彻底搞清楚这个问题，最好的办法就是顺着源代码走一遍。我们以以下版本组合为例：

spring-boot-2.7.18

logback-classic-1.2.11

SpringBoot应用启动时，会触发LoggingApplicationListener.onApplicationEnvironmentPreparedEvent方法。这个方法的核心任务之一，就是获取一个LoggingSystem的实例。这个过程如下图所示：

那么，LoggingSystem实例是如何生成的呢？关键在LoggingSystem.get这个方法里：

这里有个系统属性SYSTEM_PROPERTY，其值为org.springframework.boot.logging.LoggingSystem。它的作用是指定日志系统：

• 如果这个属性的值是一个LoggingSystem实现类的全限定名（比如org.springframework.boot.logging.logback.LogbackLoggingSystem），SpringBoot就会直接实例化它。
• 如果值被设为NONE，则会生成一个什么都不做的NoOpLoggingSystem。
• 如果既没指定也不是NONE，SpringBoot就会自动扫描类路径，寻找可用的日志框架并初始化。

拿到LoggingSystem实例后，紧接着就会调用其initialize方法：

这个方法内部会进一步调用initializeSystem：

注意这里的CONFIG_PROPERTY，它对应环境变量logging.config，也就是用来指定Logback配置文件路径的。之后，SpringBoot会使用LogbackLoggingSystem.initialize来初始化Logback：

问题就出在getLoggerContext()这个方法里。我们来看它的源代码：

看明白了吗？正是在这里，代码直接引用了StaticLoggerBinder.getSingleton().getLoggerFactory()。而在Logback 1.3.x中，这个StaticLoggerBinder类已经被移除了。所以，当SpringBoot 2.7.x试图用老办法初始化新版本的Logback时，类找不到，报错也就成了必然。

二、解决方案

分析完源码，解决方案就清晰了。核心思路就一句话：绕过SpringBoot的自动初始化，让应用自己来管理Logback的启动。

具体操作分三步：

第一步，关闭SpringBoot的日志系统自动配置。 将系统属性 org.springframework.boot.logging.LoggingSystem 的值设置为 none。这样，SpringBoot在启动时就不会尝试去初始化和绑定Logback了。

第二步，同步升级SLF4J。 将Logback升级到1.3.x时，别忘了它的搭档SLF4J也需要同步升级到1.8.x或更高版本。具体的版本对应关系，可以参考相关文档（如《Ja va：logback-classic与slf4j版本对应关系》）。

第三步，更换配置文件路径的指定方式。 如果你之前是通过环境变量 logging.config 来指定Logback配置文件（如logback.xml）的位置，现在需要改为使用Logback原生支持的 logback.configurationFile 环境变量。原因在下面的源码中一目了然：

（注：上述源码截图来自logback-classic-1.3.15）

其实，这个解决方案在Logback的官网上也有明确说明。下图来自其下载页面：

地址：https://logback.qos.ch/download.html

官网的建议也验证了我们的分析：在Spring Boot等框架中，需要通过设置org.springframework.boot.logging.LoggingSystem=none来禁用其日志系统，并直接使用Logback自身的初始化机制。

三、进一步说明

可能有人会问，为什么一定要换成logback.configurationFile，而不能继续用Spring Boot的logging.config呢？这涉及到Web应用中的初始化顺序问题。

对于部署在Servlet 3.0及以上容器（比如Tomcat）的应用，Logback的初始化通常是由ch.qos.logback.servlet.LogbackServletContainerInitializer这个类来完成的。而Spring Boot自身的初始化则是由org.springframework.web.SpringServletContainerInitializer负责。这两个类都实现了ja vax.servlet.ServletContainerInitializer接口。

关键在于，Servlet容器往往会先执行LogbackServletContainerInitializer。这意味着，在Spring Boot还没来得及插手之前，Logback就已经按照自己的规则初始化完毕了。所以，等到Spring Boot想通过logging.config去配置Logback时，时机已经错过了，配置自然不会生效。

因此，在混合升级的场景下，使用Logback原生支持的logback.configurationFile环境变量来指定配置路径，是确保配置能够被正确加载的唯一可靠方式。