一句话定位：debug=true 是 Spring Boot 自动配置的X 光透视机，它在启动时输出完整的条件评估报告，清晰展示哪些自动配置类被激活（正匹配）、哪些被跳过（负匹配）以及跳过原因，是排查自动配置问题的首选工具。

定义与作用

Spring Boot 在启动时会执行条件评估（Condition Evaluation）——逐个检查候选自动配置类上的 @ConditionalOnClass、@ConditionalOnMissingBean、@ConditionalOnProperty 等注解。这个过程默认是静默的，开发者只能看到最终的 Bean 注册结果，看不到"为什么这个配置没生效"。

debug=true 就是打开这个黑盒的开关。它让 Spring Boot 输出一份结构化的自动配置报告（Auto-configuration Report），包含：

报告内容说明排查价值
正匹配（Positive Matches）条件满足、已注册的自动配置类确认哪些自动配置生效了
负匹配（Negative Matches）条件不满足、被跳过的自动配置类排查"为什么没生效"
排除项（Exclusions）通过 exclude 显式排除的配置类确认排除规则是否生效
无条件类（Unconditional Classes）不带条件注解、总是生效的配置类识别潜在的不必要配置

对比传统 Spring：排查全靠猜

在传统 SSM 项目中，如果 DataSource 没有正确初始化，开发者需要：检查 XML 文件路径、检查 @Configuration 类是否被扫描、检查 PropertyPlaceholderConfigurer 是否加载、打印 ApplicationContext 中所有 Bean 名称逐一排查。

Spring Boot 的 debug=true 把这一切变成一份可读报告，直接告诉你"DataSourceAutoConfiguration 因为 HikariDataSource 不在类路径而被跳过"。

适用位置与常用属性

使用方式

debug=true 不是注解，而是一个配置属性，可以通过以下三种方式设置：

方式写法适用场景
application.ymldebug: true开发环境固定开启
命令行参数--debug临时排查某次启动
JVM 系统属性-DdebugCI/CD 流水线中排查

推荐配置

# application.yml（开发环境）
debug: true

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/student_db
    username: root
    password: secret

生产环境注意：debug=true 会输出大量日志，增加启动时间和日志存储成本。生产环境务必关闭，或通过 management.endpoint.conditions.enabled=true 改为通过 Actuator 端点按需查询。

核心原理

条件评估报告的生成流程

报告输出结构

关键理解：ConditionEvaluationReport 是一个启动时期的"审计日志"。即使 debug=false，它也会收集所有条件评估结果，只是不输出到控制台。这意味着你可以通过 Actuator 的 /actuator/conditions 端点（Spring Boot 2.x 默认暴露）在运行时查询这些报告。

完整示例

场景简述

飞翔科技（广州）的学生成绩管理系统 com.feixiang.student 在引入 Redis 缓存后启动报错。后端开发小崔需要排查：为什么 RedisAutoConfiguration 没有生效？到底是类路径缺失、属性配置错误，还是用户自定义 Bean 覆盖了它？架构师白歌建议他开启 debug=true，通过自动配置报告定位问题。

操作前：没有 debug=true，盲目排查

# application.yml（操作前）
spring:
  redis:
    host: localhost
    port: 6379
  datasource:
    url: jdbc:mysql://localhost:3306/student_db
    username: root
    password: secret

启动日志（操作前）：

2024-05-20 11:00:15.123  INFO 12345 --- [main] c.f.s.StudentManagementApplication : 
    Starting StudentManagementApplication using Java 1.8 on DESKTOP-FEIXIANG
2024-05-20 11:00:16.456 ERROR 12345 --- [main] c.f.s.c.CacheConfig : 
    Redis connection failed: Connection refused: localhost/127.0.0.1:6379

问题：小崔看到 Redis 连接失败，但不知道是 RedisAutoConfiguration 没生效导致他手动写的 CacheConfig 缺少 RedisConnectionFactory 注入，还是 Redis 服务器没启动。他花了 30 分钟检查 pom.xml、检查 @Configuration 类、检查配置文件，最终发现是自己写了一个自定义的 RedisTemplate Bean 导致 RedisAutoConfiguration 被 @ConditionalOnMissingBean 跳过了。

使用该特性的完整代码

小崔在架构师白歌的指导下，在 application.yml 中开启 debug=true：

# application.yml（操作后）
debug: true

spring:
  redis:
    host: localhost
    port: 6379
  datasource:
    url: jdbc:mysql://localhost:3306/student_db
    username: root
    password: secret

同时，小崔保留了之前可能冲突的自定义配置（用于演示排查）：

package com.feixiang.student.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.redis.connection.RedisConnectionFactory;
import org.springframework.data.redis.core.RedisTemplate;

@Configuration
public class CustomRedisConfig {
    
    @Bean
    public RedisTemplate<String, Object> redisTemplate(RedisConnectionFactory factory) {
        RedisTemplate<String, Object> template = new RedisTemplate<>();
        template.setConnectionFactory(factory);
        // 自定义序列化...
        return template;
    }
}

操作后运行结果及分析

开启 debug=true 后，启动日志中输出了完整的条件评估报告（关键片段）：

=========================
AUTO-CONFIGURATION REPORT
=========================

Positive Matches:
-----------------

   DataSourceAutoConfiguration
      - @ConditionalOnClass found required classes 'javax.sql.DataSource', 'com.zaxxer.hikari.HikariDataSource' (OnClassCondition)
      - @ConditionalOnMissingBean (types: javax.sql.DataSource; SearchStrategy: all) did not find any beans (OnBeanCondition)

   WebMvcAutoConfiguration
      - @ConditionalOnClass found required classes 'javax.servlet.Servlet', 'org.springframework.web.servlet.DispatcherServlet' (OnClassCondition)
      - @ConditionalOnWebApplication (required) found 'session' scope (OnWebApplicationCondition)

   RedisAutoConfiguration
      - @ConditionalOnClass found required classes 'org.springframework.data.redis.core.RedisOperations', 'io.lettuce.core.api.StatefulRedisConnection' (OnClassCondition)
      - @ConditionalOnMissingBean (types: org.springframework.data.redis.core.RedisTemplate; SearchStrategy: all) found bean 'redisTemplate' (OnBeanCondition)

Negative Matches:
-----------------

   MongoAutoConfiguration
      - @ConditionalOnClass did not find required class 'com.mongodb.client.MongoClient' (OnClassCondition)

   RabbitAutoConfiguration
      - @ConditionalOnClass did not find required class 'com.rabbitmq.client.Channel' (OnClassCondition)

Exclusions:
-----------

    None

Unconditional Classes:
----------------------

    None

分析：

  1. 正匹配：DataSourceAutoConfiguration —— 条件满足，数据源已自动配置。HikariDataSource 存在于类路径，且容器中没有用户自定义的 DataSource Bean。

  2. 正匹配：WebMvcAutoConfiguration —— 条件满足，Web MVC 已自动配置。检测到 Servlet 和 DispatcherServlet 类，且当前是 Web 应用环境。

  3. RedisAutoConfiguration 的关键线索：

    • @ConditionalOnClass 匹配：RedisOperations 和 Lettuce 类都存在，说明 spring-boot-starter-data-redis 已正确引入。
    • @ConditionalOnMissingBean 不匹配：found bean 'redisTemplate' —— 容器中已经存在名为 redisTemplate 的 Bean（就是 CustomRedisConfig 中定义的），所以 RedisAutoConfiguration 被跳过！

  4. 负匹配：MongoAutoConfiguration —— 被跳过，因为 MongoClient 不在类路径中。这是正常行为。

结论：问题不是 Redis 依赖缺失，而是 CustomRedisConfig 中自定义的 RedisTemplate 触发了 @ConditionalOnMissingBean 的退让机制。小崔有两个选择：

  • 保留自定义 RedisTemplate，删除 RedisAutoConfiguration 的期望（已经这样了）
  • 删除自定义 RedisTemplate，让 RedisAutoConfiguration 提供默认配置

易错场景与面试考点

易错场景一：把 debug=true 当成 logging.level.debug

# 错误示范：混淆 debug 的两个含义
logging:
  level:
    org.springframework.boot: debug  # 这只是日志级别，不是自动配置报告

后果：日志级别设置为 debug 后，Spring Boot 会输出大量内部日志（如 BeanFactory 创建过程），但不会输出结构化的自动配置报告。自动配置报告需要顶层的 debug: true 配置。

正确做法：

# 正确：输出自动配置报告
debug: true

# 可选：同时调整日志级别
logging:
  level:
    com.feixiang.student: debug

易错场景二：生产环境开启 debug=true 导致日志暴涨

# 错误示范：生产环境 application.yml
spring:
  profiles:
    active: prod

debug: true  # ← 生产环境不应开启！

后果：生产环境每次启动都会输出几百行自动配置报告，如果应用每天重启多次（如 Kubernetes 滚动更新），日志系统（ELK、Loki）的存储和分析成本会显著增加。更严重的是，报告内容可能暴露类路径信息（如使用了哪些第三方库），带来轻微的安全信息泄露风险。

正确做法：

# application.yml（生产环境）
spring:
  profiles:
    active: prod

# debug: true  ← 生产环境关闭

# 如需排查，通过 Actuator 端点查询
management:
  endpoints:
    web:
      exposure:
        include: health,info,conditions

通过 GET /actuator/conditions 可以运行时查看条件评估报告，无需在启动日志中输出。

面试考点

Q：debug=true 和 /actuator/conditions 有什么区别？

debug=true 在启动时将条件评估报告输出到控制台日志，适合开发环境实时查看；/actuator/conditions 在运行时通过 HTTP 端点暴露报告，适合生产环境按需排查。两者读取的是同一个 ConditionEvaluationReport 数据源，只是展示时机和方式不同。

Q：自动配置报告中的 "Positive Match" 和 "Negative Match" 分别代表什么？

Positive Match（正匹配）：条件注解全部满足，该自动配置类被加载，其中的 @Bean 被注册到容器。Negative Match（负匹配）：至少一个条件注解不满足，该自动配置类被跳过，不注册任何 Bean。Negative Match 中会列出具体哪个条件不满足以及原因（如 did not find required class 或 found bean 'xxx'）。

Q：@ConditionalOnMissingBean 在报告中显示 found bean 'xxx' 是什么意思？

这是 Negative Match 的典型原因。@ConditionalOnMissingBean 要求容器中不存在指定类型的 Bean。如果报告说 found bean 'redisTemplate'，说明容器中已经存在该 Bean（通常是用户自定义的），因此自动配置类被跳过——这是 Spring Boot "用户配置优先" 的退让机制在生效。

Q：Spring Boot 2.7.x 的条件评估报告相比 2.0 有什么改进？

Spring Boot 2.7 引入了 AutoConfiguration.imports 新文件格式，但报告结构本身保持稳定。报告现在对 AutoConfigurationImportFilter 的过滤结果也有更清晰的记录，帮助开发者区分"被条件注解跳过"和"被元数据过滤提前排除"的差异。