写日志这事，在很多 Spring Boot 项目里都是被忽略的一环。刚入行的同学习惯用 System.out.println 输出信息，上线后发现问题，翻开控制台一看，日志早被冲掉了，连异常堆栈都找不全。等到项目的确有模有样跑起来、用户量上来之后，日志就不再只是“打几行字”那么简单了。所以“springboot 使用 logback 自定义日志”这个题目，看起来只是配一个文件，实际背后涉及日志框架选型、配置文件加载机制、滚动策略、异步性能、多环境隔离、链路追踪等一系列问题。这篇文章就围绕这个标题，把我实际项目里用 Logback 做自定义日志的方案、参数选择、踩坑记录全部拆开讲一遍，适合刚接触 Spring Boot 的初学者，也适合项目日志还不规范、想补课的团队参考。
1. 为什么 Spring Boot 默认选择 Logback，以及配置文件的加载机制
1.1 SLF4J 门面和 Logback 实现的关系
先理清一个很多新人会搞混的概念：SLF4J 和 Logback 不是同一个东西。SLF4J 全称是 Simple Logging Facade for Java，它本身不干活，只定义了一套统一的日志接口。真正的日志输出动作是 Logback 在背后完成的。你可以把 SLF4J 理解成墙上的国标插座，Logback 就是符合这个规格的插头，二者配合才能通电。
项目代码里日常写的都是org.slf4j.Logger和LoggerFactory.getLogger(...)，而不是直接 new 一个 Logback 的 Logger 对象。这样写的好处是：将来如果团队想换成 Log4j2 或者其他日志实现，业务代码一行都不用改，只要调整依赖和配置文件就行。Spring Boot 的官方 starter 里已经内置了这种组合，spring-boot-starter-logging会自动引入logback-classic，同时把 Log4j、JUL（java.util.logging）通过适配层桥接到 SLF4J，保证你项目里即使有老的日志框架依赖，输出也能统一走 Logback。所以你在 Spring Boot 项目里做自定义日志，默认操作对象就是 Logback，不需要额外引入第三方日志依赖。
1.2 Spring Boot 对 Logback 的“默认约定”
不写任何配置文件时，Spring Boot 也会有一套默认的日志行为。这部分默认规则定义在spring-boot包里的base.xml中。默认只输出到控制台，格式大概是这样的：
2025-06-10T14:23:45.123+08:00 INFO 12345 --- [http-nio-8080-exec-1] com.example.demo.controller.UserController : 用户查询成功默认级别是 INFO，也就是说低于 INFO 的 DEBUG、TRACE 日志不会显示。很多同学初次接触时会觉得这个格式已经够用了，但实际项目中你会发现至少三个痛点：日志没有落盘，重启就丢；到处都是控制台输出，无法按时段、按级别归档；写死在代码里的日志级别没法动态调整。这些痛点就是“自定义日志”要解决的问题。
Spring Boot 也提供了一组简单的配置入口，比如在application.yml里这样写：
logging: level: root: info com.example.demo.mapper: debug file: name: logs/app.log这种方式适合快速验证，但它的表达能力很有限。你想实现按天滚动、单文件大小限制、异步写盘、不同环境使用不同 pattern，这些用 yml 是做不到的。所以正规做法是提供一个独立的 Logback 配置文件，完全掌控日志行为。
1.3 到底用 logback.xml 还是 logback-spring.xml
这是配置自定义日志时第一个要做的选择题。Logback 原生支持logback.xml，Spring Boot 也支持logback-spring.xml，二者都可以放在src/main/resources目录下，都能被自动加载。区别在于加载时机。
logback.xml加载得很早，早到 Spring 上下文还没完全初始化。在这个阶段，Logback 还不知道application.yml里写了什么，因此你无法在logback.xml里读取 Spring 的配置属性，也做不到根据spring.profiles.active切换不同的日志策略。而logback-spring.xml是 Spring Boot 专门留的口子，它会被 Spring 的LogbackInitializer额外处理，支持两个非常关键的标签：springProfile和springProperty。前者能根据当前激活的环境加载不同配置块，后者可以把 yml 配置文件里的属性值注入到 Logback 配置中。
所以我的结论很简单：在 Spring Boot 项目里做自定义日志，直接用logback-spring.xml，别再用logback.xml。名字虽然长一点，但灵活度完全不是一个级别。后面所有示例都基于logback-spring.xml。
2. 自定义日志的核心配置拆解与实操
2.1 三大核心对象：Logger、Appender、Layout
Logback 的体系可以拆成三个核心部分：Logger、Appender、Layout。
Logger 是你在代码里调用log.info()、log.error()时拿到的那个对象。Logger 有层级关系，名字叫com.example.demo.controller.UserController的 Logger 会自动继承com.example.demo.controller的配置，最终继承到ROOT。这种继承关系让日志级别可以逐层覆盖，不需要给每个类单独配置。
Appender 决定了日志“写到哪去”。常见的有ConsoleAppender（控制台）、FileAppender（固定文件）、RollingFileAppender（滚动文件）、AsyncAppender（异步包装器）。一个 Logger 可以绑定多个 Appender，比如业务日志既想输出到控制台，又想落盘归档，就可以挂两个 Appender。
Layout 负责格式化日志内容，决定每行日志长什么样。早期 Logback 常用PatternLayout，现在官方推荐使用 Encoder，比如PatternLayoutEncoder，因为 Encoder 可以更高效地控制输出字符集和格式。
这三者的关系可以用一条流水线来类比：Logger 是生产日志的工人，Appender 是输送日志的传送带，Layout 是决定产品外包装的机器。三者配合，才能把日志从代码里送到控制台或磁盘。
2.2 一套可以“抄作业”的基础配置模板
先给一套我在公司小项目中实际使用的配置模板，覆盖了最常见的需求：控制台输出、INFO 日志按天归档、ERROR 日志单独归档，所有文件限制大小和保留时间。
<?xml version="1.0" encoding="UTF-8"?> <configuration> <!-- 控制台输出 --> <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender"> <encoder> <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%thread] %logger{36} - %msg%n</pattern> <charset>UTF-8</charset> </encoder> </appender> <!-- INFO 日志滚动文件 --> <appender name="FILE_INFO" class="ch.qos.logback.core.rolling.RollingFileAppender"> <file>logs/app.log</file> <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy"> <fileNamePattern>logs/app.%d{yyyy-MM-dd}.%i.log</fileNamePattern> <maxFileSize>50MB</maxFileSize> <maxHistory>30</maxHistory> <totalSizeCap>10GB</totalSizeCap> </rollingPolicy> <encoder> <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%thread] %logger{36} - %msg%n</pattern> <charset>UTF-8</charset> </encoder> <filter class="ch.qos.logback.classic.filter.LevelFilter"> <level>ERROR</level> <onMatch>DENY</onMatch> <onMismatch>ACCEPT</onMismatch> </filter> </appender> <!-- ERROR 日志滚动文件 --> <appender name="FILE_ERROR" class="ch.qos.logback.core.rolling.RollingFileAppender"> <file>logs/error.log</file> <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy"> <fileNamePattern>logs/error.%d{yyyy-MM-dd}.%i.log</fileNamePattern> <maxFileSize>50MB</maxFileSize> <maxHistory>30</maxHistory> <totalSizeCap>5GB</totalSizeCap> </rollingPolicy> <encoder> <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%thread] %logger{36} - %msg%n</pattern> <charset>UTF-8</charset> </encoder> <filter class="ch.qos.logback.classic.filter.LevelFilter"> <level>ERROR</level> <onMatch>ACCEPT</onMatch> <onMismatch>DENY</onMismatch> </filter> </appender> <root level="INFO"> <appender-ref ref="CONSOLE"/> <appender-ref ref="FILE_INFO"/> <appender-ref ref="FILE_ERROR"/> </root> </configuration>这段配置里有几个细节值得说明。
第一个细节是RollingFileAppender的滚动策略。我选用的是SizeAndTimeBasedRollingPolicy，意思是“既能按天滚动，也能在单天文件超过 50MB 时继续拆分成.i后缀的文件”。文件名中的%d{yyyy-MM-dd}代表日期，%i代表当天拆分的序号。maxHistory=30表示最多保留 30 天的日志，totalSizeCap=10GB表示所有归档日志总大小超过 10GB 时，Logback 会自动删除最旧的归档。这两条参数非常重要，不然日志文件会无限增长，最后把磁盘写满。我见过不止一次因为日志把所有磁盘空间占满，导致应用直接假死的事故。
第二个细节是 ERROR 日志单独归档。我用了两个LevelFilter把 INFO 和 ERROR 分流。FILE_INFO这个 appender 遇到 ERROR 级别就拒绝，相反FILE_ERROR只接受 ERROR。这样排查线上故障时，直接打开logs/error.log就能看到所有异常，不用在几十万行 INFO 日志里人工翻找。这里有人会问，为什么不直接在代码里把 error 打两遍？因为 Logger 绑定多个 Appender 时，同一条日志会分别进入所有关联的 Appender，再用过滤器做分流，管理起来比打两遍干净得多。
2.3 异步日志的配置与参数选择
高并发接口里如果每条日志都同步刷盘，IO 会成为性能瓶颈之一。你想想，一个接口如果有 10 条日志，每条日志都等一次磁盘写入，那这些时间累积起来就是用户感知到的延迟。Logback 提供了AsyncAppender，它内部维护一个内存队列，业务线程只要把日志丢进队列就能立刻返回，真正的写盘由后台线程完成。
异步配置示例：
<appender name="ASYNC_FILE_INFO" class="ch.qos.logback.classic.AsyncAppender"> <queueSize>512</queueSize> <discardingThreshold>0</discardingThreshold> <neverBlock>true</neverBlock> <includeCallerData>false</includeCallerData> <appender-ref ref="FILE_INFO"/> </appender>然后把 root 里的FILE_INFO换成ASYNC_FILE_INFO，FILE_ERROR同理也可以包一层。这几个参数每个都有讲究。
queueSize=512控制队列长度。队列太短，并发一高就大量丢弃；太长，内存占用会上升。
discardingThreshold是丢弃阈值，默认值是queueSize的 20%。这是什么意思？举个例子，队列容量 512，当队列剩余空间不足 20% 时，Logback 会抛弃级别较低的日志（TRACE、DEBUG、INFO），只保留 WARN、ERROR。它的目的是防止队列被普通日志塞满、ERROR 进不去。但问题是你的业务日志很多都是 INFO 级，如果把 INFO 丢了，排查就没依据了。所以我把discardingThreshold设为 0，意思是队列满之前不主动丢日志。
neverBlock=true这句话非常关键。默认情况下，队列满时调用方线程会阻塞等待队列腾出位置，相当于日志系统反过来拖慢了业务线程。设置成 true 之后，队列满时日志直接丢弃，但保证业务线程不被拖死。生产环境里我建议加上，毕竟日志丢失影响的是可观测性，接口卡死影响的是可用性。牺牲一小部分日志完整性，换取业务稳定，这笔账划算。
includeCallerData=false是在告诉 Logback 不要抓取调用方信息。抓取类名、方法名、行号这些信息需要遍历调用栈，开销很大，异步场景下还会影响队列元素的大小。如果 pattern 里确实需要显示日志调用的行号，可以用%line占位符，但要注意这会增加不小的性能开销。
这个异步设计有个非常形象的类比：餐厅里后厨炒好菜，不会亲自端到每个客人桌前，而是放在传菜窗口，让传菜员统一送。传菜窗口位置有限，如果窗口满了还要硬塞，厨师就得停下炒菜等窗口空出来。neverBlock=true相当于告诉厨师：窗口满了就别塞，后面那道菜晚点上，先保证现在桌子上的菜能出。
2.4 多环境差异化管理
不同阶段的项目对日志的要求不一样。本地开发时希望日志尽量详细、输出到控制台，方便直接调试；生产环境希望保留重要信息、归档到文件，甚至输出成 JSON 方便日志平台采集。这些差异用springProfile标签在同一个logback-spring.xml里就能解决。
<springProfile name="dev"> <root level="DEBUG"> <appender-ref ref="CONSOLE"/> </root> </springProfile> <springProfile name="prod"> <root level="INFO"> <appender-ref ref="ASYNC_FILE_INFO"/> <appender-ref ref="ASYNC_FILE_ERROR"/> <appender-ref ref="CONSOLE"/> </root> </springProfile>dev 环境把 root 级别调到 DEBUG，这样 Mapper 层面的 SQL、业务中间过程的参数都能打印出来。prod 环境则保持 INFO，避免 DEBUG 日志刷爆磁盘。除此之外，如果你想在 prod 环境输出 JSON 格式日志给 ELK 采集，可以加一个LogstashEncoder的 appender：
<appender name="JSON_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> <file>logs/app.json</file> <!-- rollingPolicy 同上 --> <encoder class="ch.qos.logback.classic.encoder.JsonEncoder"/> </appender>还需要说的是，springProfile和springProperty经常搭配使用。比如 yml 里定义log.path: /data/app/logs，然后 logback-spring.xml 里用<springProperty scope="context" name="LOG_HOME" source="log.path"/>把这个变量读进来，后续用${LOG_HOME}引用。这样日志路径这种经常变化的配置就能统一收敛到配置文件里，而不是写死在 xml 中。
3. 让日志真正好用的三个进阶实战
3.1 用 MDC 实现请求全链路日志追踪
系统并发上来之后，你会遇到一个非常头疼的问题：N 个请求同时处理，日志文件里大家交叉输出，你根本不知道哪几行日志属于同一个请求。排查问题时，只能靠时间戳和线程名猜测。线程名虽然有一定参考价值，但线程池会复用线程，同一个线程可能处理多个请求，单靠它根本还原不了完整链路。
MDC（Mapped Diagnostic Context）就是 Logback 为解决这个问题提供的机制。MDC 本质是一个线程私有的 Map，你可以在处理请求的入口处放入一个请求 ID，然后 pattern 里加上%X{requestId}，同一条请求链路中的所有日志就都会带上这个 ID。
实现方式其实很简单。写一个 Filter，在请求进来时生成一个 UUID，放到 MDC 里，请求结束时移除：
@Component public class TraceIdFilter implements Filter { @Override public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain filterChain) throws IOException, ServletException { String traceId = UUID.randomUUID().toString().replace("-", ""); MDC.put("traceId", traceId); try { filterChain.doFilter(servletRequest, servletResponse); } finally { MDC.remove("traceId"); } } }对应 pattern 改成：
<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%thread] [%X{traceId}] %logger{36} - %msg%n</pattern>这样每行日志里都会有一个 traceId，同一个请求的日志天然就能串联起来。注意二点：第一，必须用finally移除 traceId。如果你忘了移除，线程池里的线程会被复用，下一个请求就会带上上一个请求的 traceId，导致链路追踪串线。第二，如果你在业务代码里用了@Async或者线程池提交了子线程任务，子线程默认是拿不到父线程 MDC 值的。要么在提交任务时手动把 MDC 的 map 传给子线程，要么用 Logback 提供的MDC.getCopyOfContextMap()和MDC.setContextMap()这两个方法来传递。
3.2 不重启修改日志级别
线上环境排查问题时，经常会遇到这种情况：日志级别配在 INFO，某个底层库只在 DEBUG 级别才输出关键参数，想看到这些参数就得改配置重启，可重启一次有风险。Spring Boot Actuator 提供了动态调整日志级别的接口，在保证安全性的前提下非常实用。
先在pom.xml引入依赖：
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-actuator</artifactId> </dependency>然后在application.yml里暴露 loggers 端点：
management: endpoints: web: exposure: include: loggers启动项目后，查看某个包的当前级别：
GET /actuator/loggers/com.example.demo.service调整级别：
POST /actuator/loggers/com.example.demo.service Content-Type: application/json {"configuredLevel": "DEBUG"}这个接口在排查问题时作用很大，但注意权限控制。生产环境不能把 actuator 所有端点都暴露给公网，只暴露必要的端点，并且配合鉴权，避免被人利用来获取敏感信息。
3.3 日志脱敏与自定义输出格式
日志里打印用户手机号、身份证号、银行卡号这类敏感信息，一旦日志泄露就是安全事故。正规做法是从源头不记录敏感字段，但很多老项目改不动，只能在输出层做一次脱敏兜底。Logback 提供了自定义转换器的方式来实现脱敏。
思路是写一个类继承ch.qos.logback.classic.pattern.MessageConverter，覆写convert方法，在输出消息前用正则把敏感信息替换掉：
public class SensitiveDataConverter extends MessageConverter { private static final Pattern PHONE_PATTERN = Pattern.compile("(1[3-9]\\d{9})"); @Override public String convert(ILoggingEvent event) { String original = event.getFormattedMessage(); if (original == null) { return ""; } Matcher matcher = PHONE_PATTERN.matcher(original); return matcher.replaceAll("$1****"); } }然后在 pattern 中把%msg替换成%converter：
<conversionRule conversionWord="converter" converterClass="com.example.demo.logging.SensitiveDataConverter"/> <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%thread] %logger{36} - %converter%n</pattern>这种做法适合作为最后一道防线，但它有个明显缺陷：日志里如果包含异步调用栈、异常详情，这些内容不会经过 MessageConverter 处理。所以脱敏不能当成唯一的隐私保护手段，归根结底还是要规范日志打印行为，不该打的信息从一开始就不要打。
4. 实战排坑清单与经验总结
4.1 高频问题速查表
做自定义日志过程中我踩过不少坑，也帮同事排查过不少，这里整理一份高频问题速查表，遇到类似问题可以直接对照。
| 现象 | 原因 | 解决方案 |
|---|---|---|
| 配置完全不生效，日志还是老样子 | 文件名写错，或者根本没放在src/main/resources下 | 检查文件名是否为logback-spring.xml，确认编译后的 classes 目录里存在该文件 |
| 自定义了 pattern，但控制台没变化 | 同时存在logback.xml和logback-spring.xml，前者优先级更高 | 删掉logback.xml，只保留logback-spring.xml |
| 日志文件路径找不到，报 FileNotFoundException | 相对路径依赖启动目录，服务以服务方式启动时工作目录不同于你预期的路径 | 配置log.path为绝对路径，比如/data/app/logs，并用springProperty注入 |
| 日志中文乱码 | encoder 未指定 UTF-8 字符集 | 在<encoder>里加<charset>UTF-8</charset> |
| MyBatis 的 SQL 日志不打印 | Mapper 接口所在包的日志级别太高 | 把对应 package 的级别设为 DEBUG，例如<logger name="com.example.demo.mapper" level="DEBUG"/> |
| 日志文件单天产出非常大，磁盘告警 | 只配了maxFileSize，没配maxHistory和totalSizeCap | 完善滚动策略，设置保留天数和总量上限 |
| 异步模式下队列丢了不少日志 | discardingThreshold用了默认值，低级别日志被主动丢弃 | 设为 0，并确认neverBlock为 true |
| ERROR 日志打印了两遍 | 多个 Appender 都包含了 ERROR，且没有做好过滤器 | 用LevelFilter做单项分流 |
这些坑看着都挺基础，但每一项都真实发生在实际项目中。尤其是配置文件同时存在多个导致不生效的问题，我刚接触 Logback 时就被折腾了一个下午。排查这个问题的技巧是：启动时看控制台里有没有 Logback 自己输出的状态信息，它会明确告诉你加载的是哪个配置文件。
除了上面表格里的问题，还有一个容易被忽略的细节：不要把日志文件路径配置在项目相对路径下。你用 IDE 启动时工作目录是项目根目录，路径没问题；但部署到服务器上，启动脚本可能是在任意一个目录执行，相对路径就会跑到奇怪的位置。最终统一方案是把日志路径收敛到application.yml，用${LOG_HOME}传入，部署时通过环境变量覆盖。
4.2 容器与部署环境下的日志策略
传统部署方式下，日志写到服务器本地文件是约定俗成的做法。但在 Docker 和 Kubernetes 环境下，这个思路要换个方向。容器本身是随时可能销毁的，如果你把日志写到容器内的本地路径，容器一删，日志就一起没了。而且现在主流的做法是用采集 Agent（比如 Filebeat、Promtail）统一收集节点日志到 ES 或者 ClickHouse，采集 Agent 通常直接从 stdout 拉取，不会一个个进容器读文件。
所以在容器化项目里，我的建议是：控制台输出仍然是主力，并且尽量输出成 JSON 格式，方便采集端解析。最简单的办法是用LogstashEncoder替代 PatternLayoutEncoder：
<appender name="JSON_CONSOLE" class="ch.qos.logback.core.ConsoleAppender"> <encoder class="net.logstash.logback.encoder.LogstashEncoder"/> </appender>这样每行日志是一个 JSON 对象，包含时间戳、级别、logger、message、traceId 等结构化字段。采集端拿到之后不需要写复杂的正则解析，直接用 JSON path 就能提取字段，后续做监控告警也方便得多。
如果你一定要在容器里保留落盘日志，建议把日志路径挂载到卷或共享存储，并用独立卷保存。但不管怎么做，都要意识到：容器是临时资源，日志的管理策略必须和容器生命周期解耦。
4.3 个人实操经验小结
日志这件事，配置越早规范化，后面排查问题越省事。我见过太多项目，上线前没人管日志，上线后出问题才翻日志，结果发现日志格式乱成一团、文件又大又杂，只能临时加配置、重启服务，整个排障过程充满痛苦。如果你现在正好在搭一个新的 Spring Boot 项目，建议把日志方案当成基础设施的一部分来设计，而不是等出了问题再补。
具体落到执行层面，我总结三条心得：
第一，日志级别不要拍脑袋定，要形成团队规范。DEBUG 是给开发人员本地调试用的，生产环境原则上不开；INFO 记录业务关键节点的执行情况；WARN 记录可以继续运行但值得关注的情况，比如重试超过次数、缓存未命中；ERROR 只记录真正需要人工介入的异常。大家严格遵守这个界限，日志才有分析价值。
第二，ERROR 日志里必须包含业务主键。比如订单支付失败，日志里只有一句“支付失败”，排查的人根本不知道是哪笔订单。正确写法是把订单号、用户 ID 都带进日志消息，或者放到 MDC 里。这样出现问题时，业务方告诉你一个订单号，你能直接翻日志定位整条链路。
第三，上线前检查日志相关的磁盘空间和备份策略。用一个很大的磁盘分区专门放日志，设置滚动策略的totalSizeCap，避免把系统盘写满导致应用崩溃。同时定期验证归档文件能正常打开、内容没有编码问题，真正验证过的备份才有意义。
5. 最后分享两个调试 Logback 的实用技巧
我在实际配置 Logback 的过程中，最痛苦的一类问题是“到底加载了哪个配置文件”“为什么我这个标签没生效”。后来发现 Logback 自身有调试模式，启动项目时加上 JVM 参数-Dlogback.debug=true，控制台会打印 Logback 内部解析配置文件的状态，包括加载路径、每个 appender 的初始化结果、过滤器的注册情况。这个参数在你怀疑配置没加载时非常有用，看到输出基本就能定位问题。
还有个技巧是关于 pattern 的。%logger{36}里的数字 36 表示 Logger 名称最多显示 36 个字符，超长部分会从包名开始缩短。这个参数对控制台对齐效果影响很大，文件日志里一般保持默认就行。如果你希望日志里展示更多的调用位置信息，可以使用%F和%L，分别表示文件名和行号。但要注意，这两个占位符在高并发场景下性能开销明显，我在生产环境的文件日志里没有启用，只在本地开发的控制台模式里保留。
回到自定义日志这件事本身，Logback 在 Spring Boot 里就像一个可以根据项目需求随意组装的工具箱。刚开始只需要能输出到控制台，慢慢你会发现需要落盘，需要滚动归档，需要异步，需要链路追踪，需要脱敏，需要 JSON 输出给日志平台。每增加一个需求，你就在现有配置上加一个 appender、加一个 filter，整个过程你可以一步步来。我个人实际体会是，第一次配置的时候最好在本地完整跑一遍所有场景，然后针对自己的业务特点再做精简，因为网上很多模板是通用型的，直接拿来用在生产上很容易出现“能跑但不适合”的情况。
