搞Java后端的时间长了你会发现一个规律代码写得再漂亮线上出了问题能救你的往往还是那些平时不起眼的日志文件。我印象最深的一次凌晨三点被叫起来排查一个订单回调丢失的问题服务一切正常接口也返回成功可数据就是对不上。最后从一台机器的日志文件里翻到一条被吞掉的异常问题五分钟定位但前面找线索却花了一个多小时。从那天起我在每个SpringBoot项目里第一件事就是把日志文件方案先定清楚。日志文件这件事说简单也简单SpringBoot内置了Logback几行配置就能出文件说复杂也复杂滚动策略、异步输出、错误日志分离、多环境切换、乱码时区每个坑我都踩过。这篇把SpringBoot日志文件的完整玩法梳理一遍从零配置到生产级方案从原理到排雷适合刚入门的同学也适合想把日志配置从“能用”提升到“好用”的人。1. 先搞清楚SpringBoot日志文件到底在记什么1.1 一条日志拆开看三个组件各司其职很多人在配置日志之前根本没想过日志是怎么从logger.info(hello)变成一行带时间、带线程、带级别的文本的。其实SpringBoot的日志体系只用理解三样东西门面、实现、配置。门面就是SLF4JSimple Logging Facade for Java它只定义接口不干活。你在代码里写的private static final Logger log LoggerFactory.getLogger(Xxx.class)用的就是SLF4J的API。好处是老生常谈的“换框架不改代码”——今天用Logback明天想换Log4j2改个依赖就行业务代码一行不用动。实现才是真正干活的人。SpringBoot默认用的是Logback这是Log4j的作者又写的一个日志框架性能更好、原生支持SLF4J、配置灵活。你在SpringBoot项目里几乎不用做任何额外引入spring-boot-starter-web里已经把Logback带上了。配置则决定了日志长什么样、写到哪、怎么滚动。这块是本文的重点。一条完整的日志输出默认长这样2025-01-12T14:23:45.12308:00 INFO 12345 --- [http-nio-8080-exec-1] com.example.demo.OrderService : 订单创建成功订单号1001拆开看时间戳、日志级别、进程ID、线程名、Logger名称通常就是类名、消息内容。这些字段不是凭空来的是Logback的Pattern布局拼出来的。你完全可以改成自己的格式比如加上traceId、去掉PID、把时间改成传统格式后面会说到。1.2 日志级别不是摆设选错了会出大事日志级别从低到高依次是TRACE、DEBUG、INFO、WARN、ERROR。Logback只会输出大于等于配置级别的日志。比如配置了INFO级别那DEBUG和TRACE就被过滤掉一条都不打印。这里有个容易犯的错有人为了调试方便直接把全局级别设成DEBUG然后原封不动带去生产。如果接口流量大日志疯狂输出DB查询参数、循环里的明细记录轻则磁盘被打满重则应用直接卡死。我真实见过一台4C8G的机器因为DEBUG日志导致CPU打满的日志进程一直在拼命写盘业务线程全在排队等锁。生产环境里我个人习惯是全局用INFO业务关键节点用INFO记录结果和核心参数异常用WARN或ERROR。DEBUG只留给那些需要精细追踪的模块而且临时开、用完关。如果不想改配置文件重启可以用Actuator动态调级别后面会单独讲。还有个小知识点日志级别是分Logger的logging.level.com.exampleDEBUG只会对com.example包及子包生效root级别管所有。利用这个特性线上排查问题时可以只放大某个业务包的日志而不是全局放大影响面小很多。1.3 动态调日志级别不用重启也能临时开DEBUG这一招是我排查线上问题时最常用的。引入spring-boot-starter-actuator然后通过/actuator/loggers端点就能实时查看和修改日志级别不用改配置、不用重启服务。curl -X POST http://localhost:8080/actuator/loggers/com.example.service.OrderService \ -H Content-Type: application/json \ -d {configuredLevel:DEBUG}这样com.example.service.OrderService这个类的日志级别就临时变成DEBUG了。等查完问题再把它设回null或者INFO恢复原样。注意线上环境Actuator端点一定要做安全控制不能裸奔至少要把management.endpoints.web.exposure.include限定为需要的端点并且放在内网或者加认证。这个功能配合日志文件一起用排查问题效率翻倍。2. 零配置起步application.yml里的日志文件设置2.1 logging.file.name 和 logging.file.path别再搞混SpringBoot默认只在控制台打印日志不写文件。想让日志落到文件里最低成本的方案就是在application.yml里加日志配置。但这里有个经典误区logging.file和logging.path是Spring Boot 2.2之前的老属性2.2之后改成了logging.file.name和logging.file.path。很多老教程还在用旧写法复制下来在今天的新项目里根本不生效。我把两个属性的区别和组合情况整理成了表格照着用就行配置方式效果只配logging.file.nameapp.log当前目录下生成app.log只配logging.file.path/var/log/myapp在/var/log/myapp目录下生成spring.log两个都配logging.file.name生效路径配置的path配置的name即/var/log/myapp/app.log注意logging.file.name可以不写路径只写文件名如果写了路径比如/var/log/app.log那path就废了。path只能指定目录文件名固定是spring.log有点反直觉所以我日常几乎只用logging.file.name路径永远写在文件名前面简单直接。配置示例logging: file: name: /var/log/myapp/app.log level: root: INFO com.example: DEBUG只要配置了这一行启动项目后就能在对应路径看到日志文件了。SpringBoot会自动创建不存在的目录不需要手动mkdir。2.2 滚动策略参数让日志文件自己“减肥”只配置文件名的话日志会一直往同一个文件里写。跑个三五天后这个文件可能就有几个GB了。到时候排查问题先想办法打开一个5GB的文本文件光是加载就卡死更别说grep了。所以必须给日志文件配置“滚动”也就是自动切割。SpringBoot为Logback提供了一套滚动策略参数不用写XML也能用logging: logback: rollingpolicy: max-file-size: 100MB max-history: 15 total-size-cap: 3GB file-name-pattern: ${LOG_FILE}.%d{yyyy-MM-dd}.%i.gzmax-file-size单个日志文件超过这个大小就触发切割默认是10MB。生产环境建议调大一点比如100MB否则日志被切成几百个小文件也不方便查。file-name-pattern历史日志的文件名格式。上面这个pattern的意思是app.log按日期再加索引滚动超过大小就是一个新文件比如app.log.2025-01-12.0.gz、app.log.2025-01-12.1.gz。注意%i必须配它是文件索引。max-history最多保留多少天的日志。这里的“天”是看上面pattern里的%d{yyyy-MM-dd}不是按系统时间简单算的。total-size-cap所有日志文件加起来的总大小上限。这个参数特别重要它管的是“所有归档日志不能超过3GB”超过就删最老的。不配的话哪怕max-history写了15天如果某天日志量特别大磁盘照样爆。很多人不理解max-history和total-size-cap的关系。简单说max-history从时间维度控制只保留最近N天total-size-cap从空间维度控制所有文件加起来不许超过NGB。两个都配是最稳妥的任何一个单独生效都有漏洞。2.3 配置优先级改了日志配置却不变先查这里SpringBoot的配置来源很多优先级从高到低是这样的命令行参数 Java系统属性 操作系统环境变量 application-{profile}.ymlprofile配置 application.yml SpringApplication默认属性。这意味着你改了application.yml里的日志级别但如果启动脚本里带了--logging.level.rootDEBUG那实际生效的是启动参数你改文件没用。宿主机环境变量LOGGING_LEVEL_ROOT同理也会覆盖配置文件。另外一个容易被无视的坑application.yml和application-prod.yml同时存在时application-prod.yml会覆盖application.yml里的同名校值。所以如果你在默认配置里写了logging.level.rootINFO又在application-prod.yml里写了DEBUG部署时激活的是prod profile那你跑生产就是DEBUG级别。排查这类问题时先看最终生效的配置是哪个来源别一上来就怀疑“日志框架坏了”。3. 进阶方案用logback-spring.xml把日志文件管明白3.1 为什么推荐logback-spring.xml而不是logback.xmlapplication.yml里的滚动策略参数虽然方便但能控制的东西有限。想要自定义日志格式、把错误日志单独写一个文件、给不同环境配不同的Appender、做异步日志最终还是得写Logback的XML配置。SpringBoot支持两种配置文件logback.xml和logback-spring.xml。强烈建议用logback-spring.xml不要用logback.xml。原因只有一个前者能直接解析SpringBoot的特性标签后者不行。logback.xml被Logback框架自己加载它不认SpringBoot的东西。你在这个文件里即使写了springProfile它也会直接报错或者忽略掉。而logback-spring.xml是由SpringBoot的初始化器加载的支持springProfile多环境配置、支持直接用${LOG_FILE}这种SpringBoot内置变量。名字多了个“spring”能力完全不同。3.2 一份可以直接抄的滚动日志文件配置下面这份配置是我在项目里常用的模板包含控制台输出、文件输出、滚动策略、UTF-8编码、多环境级别控制直接复制改个路径就能用?xml version1.0 encodingUTF-8? configuration !-- 引入SpringBoot默认的日志配置里面定义了一些变量 -- include resourceorg/springframework/boot/logging/logback/defaults.xml/ !-- 日志目录支持环境变量覆盖默认./logs -- property nameLOG_PATH value${LOG_PATH:-./logs}/ property nameAPP_NAME valuemyapp/ !-- 控制台输出 -- appender nameCONSOLE classch.qos.logback.core.ConsoleAppender encoder pattern${CONSOLE_LOG_PATTERN}/pattern charsetUTF-8/charset /encoder /appender !-- 滚动文件输出 -- appender nameFILE classch.qos.logback.core.rolling.RollingFileAppender file${LOG_PATH}/${APP_NAME}.log/file rollingPolicy classch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy fileNamePattern${LOG_PATH}/${APP_NAME}.%d{yyyy-MM-dd}.%i.log.gz/fileNamePattern maxFileSize100MB/maxFileSize maxHistory15/maxHistory totalSizeCap5GB/totalSizeCap /rollingPolicy encoder pattern%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%thread] %logger{36} - %msg%n/pattern charsetUTF-8/charset /encoder /appender !-- 开发环境方便看debug生产环境保持info只放大特定包 -- springProfile namedev logger namecom.example levelDEBUG/ /springProfile springProfile nameprod logger namecom.example levelINFO/ /springProfile root levelINFO appender-ref refCONSOLE/ appender-ref refFILE/ /root /configuration简单解释几个关键点。${LOG_PATH:-./logs}这个写法是Logback的默认值语法读取环境变量LOG_PATH如果没有就用./logs。这样部署时可以在启动脚本里通过-DLOG_PATH/var/log/myapp指定路径不改打包内的配置。SizeAndTimeBasedRollingPolicy是生产环境最常用的滚动策略同时按文件大小和日期滚动。100MB的切割阈值是我测下来比较舒服的值日志文件不算太大一行行翻也能接受切割频率又不至于太频繁。%i是索引同一分钟内产生多个切割文件时会自动编号。maxHistory15配totalSizeCap5GB是双保险。我见过只配了maxHistory没配totalSizeCap的案例某个功能突然异常一天打了20GB日志15天内磁盘就没了。所以空间上限一定要写。控制台的Pattern直接引用了SpringBoot默认的${CONSOLE_LOG_PATTERN}这是通过defaults.xml带进来的。好处是和SpringBoot默认格式一模一样带颜色、带PID。如果想自定义格式参照文件Appender里那种写法就行。3.3 错误日志单独成文件别和业务日志混在一起日志全部写进一个文件排查问题时难免要在一堆INFO里翻ERROR。更合理的做法是把ERROR级别单独写一个文件平时只盯错误日志需要看上下文再去全量日志里找。实现方式是在文件Appender上加一个过滤器appender nameERROR_FILE classch.qos.logback.core.rolling.RollingFileAppender file${LOG_PATH}/${APP_NAME}-error.log/file rollingPolicy classch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy fileNamePattern${LOG_PATH}/${APP_NAME}-error.%d{yyyy-MM-dd}.%i.log.gz/fileNamePattern maxFileSize50MB/maxFileSize maxHistory30/maxHistory totalSizeCap2GB/totalSizeCap /rollingPolicy filter classch.qos.logback.classic.filter.LevelFilter levelERROR/level onMatchACCEPT/onMatch onMismatchDENY/onMismatch /filter encoder pattern%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%thread] %logger{36} - %msg%n/pattern charsetUTF-8/charset /encoder /appender注意这里用的是LevelFilter而不是ThresholdFilter。ThresholdFilter是阈值过滤器配了ERROR就会把ERROR和以上级别都放进来LevelFilter是精确匹配配了ERROR就只放ERROR。想要WARN也进来那就再叠加一个过滤器或用阈值。然后把这个Appender加进logger或者rootroot levelINFO appender-ref refCONSOLE/ appender-ref refFILE/ appender-ref refERROR_FILE/ /root这里有个需要知道的概念叫“日志继承”。默认情况下一个logger输出了日志会一路向上传递给root由root配置的所有Appender处理。如果你给某个子logger单独加了一个Appender它又会传给root导致同一条日志被写两遍。解决办法是给子logger设置additivityfalse切断向上传递。上面这个方案里ERROR_FILE挂在root上不是挂在子logger上所以不会重复输出。3.4 异步日志别让日志拖慢接口响应日志写文件本身是有开销的。磁盘IO在低并发场景下无所谓一旦接口QPS上来同步写日志会占用业务线程时间极端情况下日志反而成了性能瓶颈。解决办法是加一层异步业务线程只管把日志丢进内存队列后台线程批量写磁盘。在Logback里用AsyncAppender包一层就行appender nameASYNC_FILE classch.qos.logback.classic.AsyncAppender queueSize1024/queueSize discardingThreshold0/discardingThreshold neverBlocktrue/neverBlock appender-ref refFILE/ /appender然后把appender-ref refFILE/换成appender-ref refASYNC_FILE/。queueSize是队列容量默认256一般需求1024足够了。neverBlocktrue的意思是队列满了不阻塞业务线程直接把日志丢掉保证接口响应速度。这里有三个参数要想清楚queueSize太小会频繁丢日志太大会占内存。1024意味着最多积压1024条日志每条按1KB算也就1MB左右完全可以接受。discardingThreshold默认值是队列剩余容量20%时开始丢弃TRACE/DEBUG/INFO保留WARN/ERROR。如果想更保险设成0表示队列无论多满都不丢弃除非neverBlocktrue。neverBlock设成true业务线程永远不会被日志拖住但极端情况下会丢日志。设成false队列满时业务线程会阻塞等待队列腾出空间性能下降但日志不丢。我的建议是普通业务系统用discardingThreshold0, neverBlocktrue优先保证业务不受影响对日志完整性要求极高的财务、审计类系统设置neverBlockfalse用牺牲少量性能换日志不丢失。4. 生产环境日志文件排雷实录4.1 日志文件不生成、不写入排查清单这类问题很多新手遇到过配置看着没问题但日志文件就是不出现或者出现了却是空的。这时候按下面顺序排查命中率很高第一确认配置文件名对不对。SpringBoot识别的配置文件是logback-spring.xml或logback.xml放在src/main/resources下。如果你命名成logback-test.xml那会被测试环境用命名成logback-prod.xml之类SpringBoot根本不会自动加载。第二确认是否引入了其他日志配置文件。项目里如果同时存在logback.xml和logback-spring.xmlSpringBoot加载的是logback-spring.xmllogback.xml会被忽略。如果两个文件内容不一致以logback-spring.xml为准。第三确认日志目录是否有写权限。SpringBoot在Linux部署时/var/log/myapp这种系统目录经常没有写权限。启动日志里会提示Failed to create parent directories或者Permission denied。最简单的验证方式是手动执行mkdir -p /var/log/myapp touch /var/log/myapp/test.log能创建就说明权限没问题。第四确认Appender有没有被引用。这个属于低级错误定义了FILEAppender但root或者logger里忘了写appender-ref refFILE/文件自然就不会生成。检查XML时务必确认Appender定义和引用都齐全。4.2 乱码、时间不准、磁盘爆满三个高频事故乱码问题。日志里的中文全是???或者乱码绝大多数是编码问题。解决方案就是在Encoder里强制指定UTF-8至少在XML里加上charsetUTF-8/charset不要依赖系统默认编码。我之前在Windows上开发时日志正常部署到Linux服务器就乱码就是因为Linux的默认编码是UTF-8但Windows上IDEA控制台窗口的默认编码是GBK。统一在这里配置之后除非日志文件编辑器打开编码不对否则不会再乱。时间不准。跑在服务器上日志时间比本机慢8小时或者对不上。这个是宿主机时区问题。Logback的%d默认用系统时区SpringBoot默认用JVM时区。解决办法有几种启动参数加-Duser.timezoneGMT8或者在XML的Pattern里指定时区%d{yyyy-MM-dd HH:mm:ss.SSS, GMT8}。两个方法都行我个人推荐后者因为它直接写在日志配置里换台机器也生效不依赖JVM参数。磁盘爆满。这个最凶险。日志写满磁盘会导致应用假死、数据库连接断掉、容器健康检查失败。我见过最惨的一次是服务直接OOM因为日志线程疯狂写盘磁盘满了之后IO一直阻塞内存里积压了大量待写日志。预防就一条滚动策略里的totalSizeCap必须配并且估算好上限。怎么估算假设系统每天最多产生2GB日志这个量和接口QPS、日志级别强相关保留15天那总上限可以设成30GB。如果磁盘总共才100GB还要给系统文件、数据文件留余地那totalSizeCap就得再降比如15GB。这个值没有标准答案按“一天最大日志量乘以保留天数再留20%余量”算比较合理。4.3 从Spring Boot 2.x升级到3.x日志文件配置有哪些变化升级到Spring Boot 3.x后日志这块踩过两次坑这里一起说了。第一次是logging.file和logging.path这两个老属性。Spring Boot 2.2就标了deprecated2.x还能用3.x直接不认了。如果你是从老项目升级的记得把所有logging.file改成logging.file.name所有logging.path改成logging.file.path否则日志配置静默失效应用重启后既不写文件也不报错特别隐蔽。第二次是Logback版本变化。Spring Boot 3.x内部升级到了Logback 1.4.x和1.2.x在少数API上有差异。如果你之前的logback-spring.xml用了比较冷门的自定义组件或者美化了Pattern可能在启动时报错。常规配置不受影响。我遇到过的问题是SizeAndTimeBasedRollingPolicy的totalSizeCap属性在1.4.x里行为有微调旧配置里没写maxHistory只写totalSizeCap升级后日志保留天数超出预期。现在我的习惯是maxHistory和totalSizeCap两个都写不管Logback哪个版本行为都不会跑偏。Spring Boot 3.x默认日志框架还是Logback这一点没变不用慌。spring-boot-starter-logging依然被自动引入绝大多数旧配置都能直接迁移。5. 我的日志文件配置习惯最后分享几个这几年留下的固定习惯不一定适合所有项目但对大多数SpringBoot应用是通用经验。配置上我坚持用logback-spring.xml不依赖application.yml里的简化配置。虽然简化配置很省事但一旦需求复杂起来比如多环境不同日志路径、错误日志单独文件、异步输出最终还是要回到XML。与其到时候再迁移不如从第一天就用XML。路径上我约定所有日志统一放在/var/log/${APP_NAME}/目录文件名按应用区分滚动归档加后缀.gz。这样部署多模块时一台机器上不同应用的日志不会混在一起而.gz能省不少磁盘空间。生产环境的日志级别我只会开INFO但会给核心业务包单独开DEBUG用于初期观察稳定后再关掉。排查问题时优先用Actuator动态调级别尽量避免重启服务毕竟生产重启一次的成本很高。再送一个排查建议日志文件配置好之后模拟一条报错日志马上确认三件事——文件生成了没有、内容编码对不对、时间是不是预期时区。这三关过了上线后日志方面出问题的概率会小很多。其实日志文件这套东西说难不难但它属于那种“平时没感觉、出事就救命”的基础设施。花十几分钟把配置规范起来省掉的是以后不知道多少个凌晨排查问题的夜晚。
SpringBoot日志文件配置全指南：从零到生产级
搞Java后端的时间长了你会发现一个规律代码写得再漂亮线上出了问题能救你的往往还是那些平时不起眼的日志文件。我印象最深的一次凌晨三点被叫起来排查一个订单回调丢失的问题服务一切正常接口也返回成功可数据就是对不上。最后从一台机器的日志文件里翻到一条被吞掉的异常问题五分钟定位但前面找线索却花了一个多小时。从那天起我在每个SpringBoot项目里第一件事就是把日志文件方案先定清楚。日志文件这件事说简单也简单SpringBoot内置了Logback几行配置就能出文件说复杂也复杂滚动策略、异步输出、错误日志分离、多环境切换、乱码时区每个坑我都踩过。这篇把SpringBoot日志文件的完整玩法梳理一遍从零配置到生产级方案从原理到排雷适合刚入门的同学也适合想把日志配置从“能用”提升到“好用”的人。1. 先搞清楚SpringBoot日志文件到底在记什么1.1 一条日志拆开看三个组件各司其职很多人在配置日志之前根本没想过日志是怎么从logger.info(hello)变成一行带时间、带线程、带级别的文本的。其实SpringBoot的日志体系只用理解三样东西门面、实现、配置。门面就是SLF4JSimple Logging Facade for Java它只定义接口不干活。你在代码里写的private static final Logger log LoggerFactory.getLogger(Xxx.class)用的就是SLF4J的API。好处是老生常谈的“换框架不改代码”——今天用Logback明天想换Log4j2改个依赖就行业务代码一行不用动。实现才是真正干活的人。SpringBoot默认用的是Logback这是Log4j的作者又写的一个日志框架性能更好、原生支持SLF4J、配置灵活。你在SpringBoot项目里几乎不用做任何额外引入spring-boot-starter-web里已经把Logback带上了。配置则决定了日志长什么样、写到哪、怎么滚动。这块是本文的重点。一条完整的日志输出默认长这样2025-01-12T14:23:45.12308:00 INFO 12345 --- [http-nio-8080-exec-1] com.example.demo.OrderService : 订单创建成功订单号1001拆开看时间戳、日志级别、进程ID、线程名、Logger名称通常就是类名、消息内容。这些字段不是凭空来的是Logback的Pattern布局拼出来的。你完全可以改成自己的格式比如加上traceId、去掉PID、把时间改成传统格式后面会说到。1.2 日志级别不是摆设选错了会出大事日志级别从低到高依次是TRACE、DEBUG、INFO、WARN、ERROR。Logback只会输出大于等于配置级别的日志。比如配置了INFO级别那DEBUG和TRACE就被过滤掉一条都不打印。这里有个容易犯的错有人为了调试方便直接把全局级别设成DEBUG然后原封不动带去生产。如果接口流量大日志疯狂输出DB查询参数、循环里的明细记录轻则磁盘被打满重则应用直接卡死。我真实见过一台4C8G的机器因为DEBUG日志导致CPU打满的日志进程一直在拼命写盘业务线程全在排队等锁。生产环境里我个人习惯是全局用INFO业务关键节点用INFO记录结果和核心参数异常用WARN或ERROR。DEBUG只留给那些需要精细追踪的模块而且临时开、用完关。如果不想改配置文件重启可以用Actuator动态调级别后面会单独讲。还有个小知识点日志级别是分Logger的logging.level.com.exampleDEBUG只会对com.example包及子包生效root级别管所有。利用这个特性线上排查问题时可以只放大某个业务包的日志而不是全局放大影响面小很多。1.3 动态调日志级别不用重启也能临时开DEBUG这一招是我排查线上问题时最常用的。引入spring-boot-starter-actuator然后通过/actuator/loggers端点就能实时查看和修改日志级别不用改配置、不用重启服务。curl -X POST http://localhost:8080/actuator/loggers/com.example.service.OrderService \ -H Content-Type: application/json \ -d {configuredLevel:DEBUG}这样com.example.service.OrderService这个类的日志级别就临时变成DEBUG了。等查完问题再把它设回null或者INFO恢复原样。注意线上环境Actuator端点一定要做安全控制不能裸奔至少要把management.endpoints.web.exposure.include限定为需要的端点并且放在内网或者加认证。这个功能配合日志文件一起用排查问题效率翻倍。2. 零配置起步application.yml里的日志文件设置2.1 logging.file.name 和 logging.file.path别再搞混SpringBoot默认只在控制台打印日志不写文件。想让日志落到文件里最低成本的方案就是在application.yml里加日志配置。但这里有个经典误区logging.file和logging.path是Spring Boot 2.2之前的老属性2.2之后改成了logging.file.name和logging.file.path。很多老教程还在用旧写法复制下来在今天的新项目里根本不生效。我把两个属性的区别和组合情况整理成了表格照着用就行配置方式效果只配logging.file.nameapp.log当前目录下生成app.log只配logging.file.path/var/log/myapp在/var/log/myapp目录下生成spring.log两个都配logging.file.name生效路径配置的path配置的name即/var/log/myapp/app.log注意logging.file.name可以不写路径只写文件名如果写了路径比如/var/log/app.log那path就废了。path只能指定目录文件名固定是spring.log有点反直觉所以我日常几乎只用logging.file.name路径永远写在文件名前面简单直接。配置示例logging: file: name: /var/log/myapp/app.log level: root: INFO com.example: DEBUG只要配置了这一行启动项目后就能在对应路径看到日志文件了。SpringBoot会自动创建不存在的目录不需要手动mkdir。2.2 滚动策略参数让日志文件自己“减肥”只配置文件名的话日志会一直往同一个文件里写。跑个三五天后这个文件可能就有几个GB了。到时候排查问题先想办法打开一个5GB的文本文件光是加载就卡死更别说grep了。所以必须给日志文件配置“滚动”也就是自动切割。SpringBoot为Logback提供了一套滚动策略参数不用写XML也能用logging: logback: rollingpolicy: max-file-size: 100MB max-history: 15 total-size-cap: 3GB file-name-pattern: ${LOG_FILE}.%d{yyyy-MM-dd}.%i.gzmax-file-size单个日志文件超过这个大小就触发切割默认是10MB。生产环境建议调大一点比如100MB否则日志被切成几百个小文件也不方便查。file-name-pattern历史日志的文件名格式。上面这个pattern的意思是app.log按日期再加索引滚动超过大小就是一个新文件比如app.log.2025-01-12.0.gz、app.log.2025-01-12.1.gz。注意%i必须配它是文件索引。max-history最多保留多少天的日志。这里的“天”是看上面pattern里的%d{yyyy-MM-dd}不是按系统时间简单算的。total-size-cap所有日志文件加起来的总大小上限。这个参数特别重要它管的是“所有归档日志不能超过3GB”超过就删最老的。不配的话哪怕max-history写了15天如果某天日志量特别大磁盘照样爆。很多人不理解max-history和total-size-cap的关系。简单说max-history从时间维度控制只保留最近N天total-size-cap从空间维度控制所有文件加起来不许超过NGB。两个都配是最稳妥的任何一个单独生效都有漏洞。2.3 配置优先级改了日志配置却不变先查这里SpringBoot的配置来源很多优先级从高到低是这样的命令行参数 Java系统属性 操作系统环境变量 application-{profile}.ymlprofile配置 application.yml SpringApplication默认属性。这意味着你改了application.yml里的日志级别但如果启动脚本里带了--logging.level.rootDEBUG那实际生效的是启动参数你改文件没用。宿主机环境变量LOGGING_LEVEL_ROOT同理也会覆盖配置文件。另外一个容易被无视的坑application.yml和application-prod.yml同时存在时application-prod.yml会覆盖application.yml里的同名校值。所以如果你在默认配置里写了logging.level.rootINFO又在application-prod.yml里写了DEBUG部署时激活的是prod profile那你跑生产就是DEBUG级别。排查这类问题时先看最终生效的配置是哪个来源别一上来就怀疑“日志框架坏了”。3. 进阶方案用logback-spring.xml把日志文件管明白3.1 为什么推荐logback-spring.xml而不是logback.xmlapplication.yml里的滚动策略参数虽然方便但能控制的东西有限。想要自定义日志格式、把错误日志单独写一个文件、给不同环境配不同的Appender、做异步日志最终还是得写Logback的XML配置。SpringBoot支持两种配置文件logback.xml和logback-spring.xml。强烈建议用logback-spring.xml不要用logback.xml。原因只有一个前者能直接解析SpringBoot的特性标签后者不行。logback.xml被Logback框架自己加载它不认SpringBoot的东西。你在这个文件里即使写了springProfile它也会直接报错或者忽略掉。而logback-spring.xml是由SpringBoot的初始化器加载的支持springProfile多环境配置、支持直接用${LOG_FILE}这种SpringBoot内置变量。名字多了个“spring”能力完全不同。3.2 一份可以直接抄的滚动日志文件配置下面这份配置是我在项目里常用的模板包含控制台输出、文件输出、滚动策略、UTF-8编码、多环境级别控制直接复制改个路径就能用?xml version1.0 encodingUTF-8? configuration !-- 引入SpringBoot默认的日志配置里面定义了一些变量 -- include resourceorg/springframework/boot/logging/logback/defaults.xml/ !-- 日志目录支持环境变量覆盖默认./logs -- property nameLOG_PATH value${LOG_PATH:-./logs}/ property nameAPP_NAME valuemyapp/ !-- 控制台输出 -- appender nameCONSOLE classch.qos.logback.core.ConsoleAppender encoder pattern${CONSOLE_LOG_PATTERN}/pattern charsetUTF-8/charset /encoder /appender !-- 滚动文件输出 -- appender nameFILE classch.qos.logback.core.rolling.RollingFileAppender file${LOG_PATH}/${APP_NAME}.log/file rollingPolicy classch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy fileNamePattern${LOG_PATH}/${APP_NAME}.%d{yyyy-MM-dd}.%i.log.gz/fileNamePattern maxFileSize100MB/maxFileSize maxHistory15/maxHistory totalSizeCap5GB/totalSizeCap /rollingPolicy encoder pattern%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%thread] %logger{36} - %msg%n/pattern charsetUTF-8/charset /encoder /appender !-- 开发环境方便看debug生产环境保持info只放大特定包 -- springProfile namedev logger namecom.example levelDEBUG/ /springProfile springProfile nameprod logger namecom.example levelINFO/ /springProfile root levelINFO appender-ref refCONSOLE/ appender-ref refFILE/ /root /configuration简单解释几个关键点。${LOG_PATH:-./logs}这个写法是Logback的默认值语法读取环境变量LOG_PATH如果没有就用./logs。这样部署时可以在启动脚本里通过-DLOG_PATH/var/log/myapp指定路径不改打包内的配置。SizeAndTimeBasedRollingPolicy是生产环境最常用的滚动策略同时按文件大小和日期滚动。100MB的切割阈值是我测下来比较舒服的值日志文件不算太大一行行翻也能接受切割频率又不至于太频繁。%i是索引同一分钟内产生多个切割文件时会自动编号。maxHistory15配totalSizeCap5GB是双保险。我见过只配了maxHistory没配totalSizeCap的案例某个功能突然异常一天打了20GB日志15天内磁盘就没了。所以空间上限一定要写。控制台的Pattern直接引用了SpringBoot默认的${CONSOLE_LOG_PATTERN}这是通过defaults.xml带进来的。好处是和SpringBoot默认格式一模一样带颜色、带PID。如果想自定义格式参照文件Appender里那种写法就行。3.3 错误日志单独成文件别和业务日志混在一起日志全部写进一个文件排查问题时难免要在一堆INFO里翻ERROR。更合理的做法是把ERROR级别单独写一个文件平时只盯错误日志需要看上下文再去全量日志里找。实现方式是在文件Appender上加一个过滤器appender nameERROR_FILE classch.qos.logback.core.rolling.RollingFileAppender file${LOG_PATH}/${APP_NAME}-error.log/file rollingPolicy classch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy fileNamePattern${LOG_PATH}/${APP_NAME}-error.%d{yyyy-MM-dd}.%i.log.gz/fileNamePattern maxFileSize50MB/maxFileSize maxHistory30/maxHistory totalSizeCap2GB/totalSizeCap /rollingPolicy filter classch.qos.logback.classic.filter.LevelFilter levelERROR/level onMatchACCEPT/onMatch onMismatchDENY/onMismatch /filter encoder pattern%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%thread] %logger{36} - %msg%n/pattern charsetUTF-8/charset /encoder /appender注意这里用的是LevelFilter而不是ThresholdFilter。ThresholdFilter是阈值过滤器配了ERROR就会把ERROR和以上级别都放进来LevelFilter是精确匹配配了ERROR就只放ERROR。想要WARN也进来那就再叠加一个过滤器或用阈值。然后把这个Appender加进logger或者rootroot levelINFO appender-ref refCONSOLE/ appender-ref refFILE/ appender-ref refERROR_FILE/ /root这里有个需要知道的概念叫“日志继承”。默认情况下一个logger输出了日志会一路向上传递给root由root配置的所有Appender处理。如果你给某个子logger单独加了一个Appender它又会传给root导致同一条日志被写两遍。解决办法是给子logger设置additivityfalse切断向上传递。上面这个方案里ERROR_FILE挂在root上不是挂在子logger上所以不会重复输出。3.4 异步日志别让日志拖慢接口响应日志写文件本身是有开销的。磁盘IO在低并发场景下无所谓一旦接口QPS上来同步写日志会占用业务线程时间极端情况下日志反而成了性能瓶颈。解决办法是加一层异步业务线程只管把日志丢进内存队列后台线程批量写磁盘。在Logback里用AsyncAppender包一层就行appender nameASYNC_FILE classch.qos.logback.classic.AsyncAppender queueSize1024/queueSize discardingThreshold0/discardingThreshold neverBlocktrue/neverBlock appender-ref refFILE/ /appender然后把appender-ref refFILE/换成appender-ref refASYNC_FILE/。queueSize是队列容量默认256一般需求1024足够了。neverBlocktrue的意思是队列满了不阻塞业务线程直接把日志丢掉保证接口响应速度。这里有三个参数要想清楚queueSize太小会频繁丢日志太大会占内存。1024意味着最多积压1024条日志每条按1KB算也就1MB左右完全可以接受。discardingThreshold默认值是队列剩余容量20%时开始丢弃TRACE/DEBUG/INFO保留WARN/ERROR。如果想更保险设成0表示队列无论多满都不丢弃除非neverBlocktrue。neverBlock设成true业务线程永远不会被日志拖住但极端情况下会丢日志。设成false队列满时业务线程会阻塞等待队列腾出空间性能下降但日志不丢。我的建议是普通业务系统用discardingThreshold0, neverBlocktrue优先保证业务不受影响对日志完整性要求极高的财务、审计类系统设置neverBlockfalse用牺牲少量性能换日志不丢失。4. 生产环境日志文件排雷实录4.1 日志文件不生成、不写入排查清单这类问题很多新手遇到过配置看着没问题但日志文件就是不出现或者出现了却是空的。这时候按下面顺序排查命中率很高第一确认配置文件名对不对。SpringBoot识别的配置文件是logback-spring.xml或logback.xml放在src/main/resources下。如果你命名成logback-test.xml那会被测试环境用命名成logback-prod.xml之类SpringBoot根本不会自动加载。第二确认是否引入了其他日志配置文件。项目里如果同时存在logback.xml和logback-spring.xmlSpringBoot加载的是logback-spring.xmllogback.xml会被忽略。如果两个文件内容不一致以logback-spring.xml为准。第三确认日志目录是否有写权限。SpringBoot在Linux部署时/var/log/myapp这种系统目录经常没有写权限。启动日志里会提示Failed to create parent directories或者Permission denied。最简单的验证方式是手动执行mkdir -p /var/log/myapp touch /var/log/myapp/test.log能创建就说明权限没问题。第四确认Appender有没有被引用。这个属于低级错误定义了FILEAppender但root或者logger里忘了写appender-ref refFILE/文件自然就不会生成。检查XML时务必确认Appender定义和引用都齐全。4.2 乱码、时间不准、磁盘爆满三个高频事故乱码问题。日志里的中文全是???或者乱码绝大多数是编码问题。解决方案就是在Encoder里强制指定UTF-8至少在XML里加上charsetUTF-8/charset不要依赖系统默认编码。我之前在Windows上开发时日志正常部署到Linux服务器就乱码就是因为Linux的默认编码是UTF-8但Windows上IDEA控制台窗口的默认编码是GBK。统一在这里配置之后除非日志文件编辑器打开编码不对否则不会再乱。时间不准。跑在服务器上日志时间比本机慢8小时或者对不上。这个是宿主机时区问题。Logback的%d默认用系统时区SpringBoot默认用JVM时区。解决办法有几种启动参数加-Duser.timezoneGMT8或者在XML的Pattern里指定时区%d{yyyy-MM-dd HH:mm:ss.SSS, GMT8}。两个方法都行我个人推荐后者因为它直接写在日志配置里换台机器也生效不依赖JVM参数。磁盘爆满。这个最凶险。日志写满磁盘会导致应用假死、数据库连接断掉、容器健康检查失败。我见过最惨的一次是服务直接OOM因为日志线程疯狂写盘磁盘满了之后IO一直阻塞内存里积压了大量待写日志。预防就一条滚动策略里的totalSizeCap必须配并且估算好上限。怎么估算假设系统每天最多产生2GB日志这个量和接口QPS、日志级别强相关保留15天那总上限可以设成30GB。如果磁盘总共才100GB还要给系统文件、数据文件留余地那totalSizeCap就得再降比如15GB。这个值没有标准答案按“一天最大日志量乘以保留天数再留20%余量”算比较合理。4.3 从Spring Boot 2.x升级到3.x日志文件配置有哪些变化升级到Spring Boot 3.x后日志这块踩过两次坑这里一起说了。第一次是logging.file和logging.path这两个老属性。Spring Boot 2.2就标了deprecated2.x还能用3.x直接不认了。如果你是从老项目升级的记得把所有logging.file改成logging.file.name所有logging.path改成logging.file.path否则日志配置静默失效应用重启后既不写文件也不报错特别隐蔽。第二次是Logback版本变化。Spring Boot 3.x内部升级到了Logback 1.4.x和1.2.x在少数API上有差异。如果你之前的logback-spring.xml用了比较冷门的自定义组件或者美化了Pattern可能在启动时报错。常规配置不受影响。我遇到过的问题是SizeAndTimeBasedRollingPolicy的totalSizeCap属性在1.4.x里行为有微调旧配置里没写maxHistory只写totalSizeCap升级后日志保留天数超出预期。现在我的习惯是maxHistory和totalSizeCap两个都写不管Logback哪个版本行为都不会跑偏。Spring Boot 3.x默认日志框架还是Logback这一点没变不用慌。spring-boot-starter-logging依然被自动引入绝大多数旧配置都能直接迁移。5. 我的日志文件配置习惯最后分享几个这几年留下的固定习惯不一定适合所有项目但对大多数SpringBoot应用是通用经验。配置上我坚持用logback-spring.xml不依赖application.yml里的简化配置。虽然简化配置很省事但一旦需求复杂起来比如多环境不同日志路径、错误日志单独文件、异步输出最终还是要回到XML。与其到时候再迁移不如从第一天就用XML。路径上我约定所有日志统一放在/var/log/${APP_NAME}/目录文件名按应用区分滚动归档加后缀.gz。这样部署多模块时一台机器上不同应用的日志不会混在一起而.gz能省不少磁盘空间。生产环境的日志级别我只会开INFO但会给核心业务包单独开DEBUG用于初期观察稳定后再关掉。排查问题时优先用Actuator动态调级别尽量避免重启服务毕竟生产重启一次的成本很高。再送一个排查建议日志文件配置好之后模拟一条报错日志马上确认三件事——文件生成了没有、内容编码对不对、时间是不是预期时区。这三关过了上线后日志方面出问题的概率会小很多。其实日志文件这套东西说难不难但它属于那种“平时没感觉、出事就救命”的基础设施。花十几分钟把配置规范起来省掉的是以后不知道多少个凌晨排查问题的夜晚。