1. 项目缘起从控制台那行“Spring”说起如果你和我一样每天启动Spring Boot项目的次数比喝水的次数还多那你一定对下面这行字熟悉得不能再熟悉了. ____ _ __ _ _ /\\ / ____ __ _ _(_)_ __ __ _ \ \ \ \ ( ( )\___ | _ | _| | _ \/ _ | \ \ \ \ \\/ ___)| |_)| | | | | || (_| | ) ) ) ) |____| .__|_| |_|_| |_\__, | / / / / |_||___//_/_/_/ :: Spring Boot :: (v3.2.5)这就是Spring Boot的默认Banner。它就像一个项目的“开机画面”每次应用启动时都会在控制台率先打印出来。一开始你可能觉得它挺酷但看久了尤其是在微服务架构下十几个服务同时启动满屏都是几乎一模一样的“Spring”你可能会开始思考能不能让它变得不一样一点比如把公司Logo放上去或者显示当前环境、版本号甚至来点ASCII艺术让启动日志变得更有辨识度、更有趣这就是自定义Banner的初衷。它远不止是“花里胡哨”的表面功夫。在一个拥有数十个微服务的系统中通过定制化的Banner你可以一眼就从启动日志的海洋中快速定位到是哪个服务、哪个版本、在哪个环境开发、测试、生产下启动了。这对于日常开发、问题排查和运维监控来说是一个成本极低但收益显著的“小技巧”。今天我们就来彻底搞懂Spring Boot的自定义Banner。我会从最简单的文本替换讲到复杂的动态生成从内置变量使用到结合Profile实现环境差异化最后还会分享几个我踩过的“坑”和让Banner“活”起来的进阶玩法。无论你是想简单换个Logo还是想打造一个信息丰富的启动面板这篇内容都能给你答案。2. Banner的运作机制与核心配置解析在动手修改之前我们得先明白Spring Boot是怎么处理这个Banner的。理解了这个过程后面无论遇到什么问题你都能自己找到根源。2.1 Spring Boot的Banner加载流程Spring Boot在应用启动的非常早期阶段——甚至在ApplicationContext创建之前——就会去加载和打印Banner。这个过程主要由SpringApplicationBannerPrinter类负责。它的工作逻辑可以概括为以下几步确定Banner模式首先Spring Boot会检查当前的运行模式。它支持三种模式OFF关闭、CONSOLE仅输出到控制台、LOG仅输出到日志文件。这个模式由spring.main.banner-mode属性控制。按优先级查找Banner文件如果模式不是OFF它会按照一个明确的优先级顺序去寻找Banner内容。这个优先级是理解自定义Banner的关键最高优先级在代码中通过SpringApplication.setBanner(...)方法直接设置的Banner接口实现。文件优先级在项目的资源目录通常是src/main/resources下查找名为banner.txt、banner.gif、banner.jpg或banner.png的文件。默认兜底如果以上都未找到则使用内置的SpringBootBanner也就是我们开头看到的那段经典ASCII艺术字。注意这里有一个非常重要的细节。对于图像文件gif/jpg/pngSpring Boot会尝试将其转换为ASCII字符画再输出。而对于banner.txt则是直接读取文本内容。banner.txt的优先级高于图像文件。也就是说如果你同时存在banner.txt和banner.pngSpring Boot会使用banner.txt的内容。渲染与打印找到Banner源后会使用一个Banner接口的实现如ResourceBanner、ImageBanner来渲染内容最终输出到指定的目标控制台或日志。2.2 核心配置属性一览大部分自定义行为都可以通过application.properties或application.yml文件来配置。以下是所有与Banner相关的配置项在application.properties中# 控制Banner输出模式 spring.main.banner-modeconsole # 可选值off, console, log # 自定义Banner文件的位置和名称如果你不想用默认的banner.txt spring.banner.locationclasspath:my-banner.txt # 自定义图像Banner的位置 spring.banner.image.locationclasspath:logo.png # 图像Banner的转换设置 spring.banner.image.width76 # 输出字符画的宽度字符数 spring.banner.image.height20 # 输出字符画的高度字符数 spring.banner.image.invertfalse # 是否反转颜色深色背景用 spring.banner.image.pixelmodeTEXT # 像素模式可选TEXT, BLOCK在application.yml中spring: main: banner-mode: console banner: location: classpath:my-banner.txt image: location: classpath:logo.png width: 76 height: 20 invert: false pixelmode: TEXTspring.banner.location属性非常强大。它允许你将Banner文件放在任何类路径可访问的位置或者使用file:前缀指定绝对路径。这为多环境、多配置的Banner管理提供了灵活性。3. 手把手实战创建你的第一个自定义Banner理论说再多不如动手试一次。我们从最简单的文本Banner开始。3.1 创建文本Banner (banner.txt)在你的Spring Boot项目的资源目录下src/main/resources/创建一个新文件命名为banner.txt。用任何文本编辑器打开它输入你想要的ASCII艺术字或文本。你可以从网上找一些ASCII艺术生成网站把公司名、项目名或者一句格言转换进去。例如一个简单的版本 My Awesome Application v1.0.0 启动你的Spring Boot应用你会看到默认的Spring Banner被替换成了你自定义的内容。3.2 使用内置的占位符变量如果Banner只能显示静态文本那它的作用就大打折扣了。Spring Boot允许我们在banner.txt中使用预定义的占位符来动态注入应用信息。这些变量在渲染时会被自动替换。变量名说明示例值${application.title}MANIFEST.MF中定义的应用标题或默认为spring.application.namemy-app${application.version}应用的版本号来自pom.xml或build.gradle1.0.0${spring-boot.version}正在使用的Spring Boot版本3.2.5${application.formatted-version}格式化的版本号在版本号前加vv1.0.0${Ansi.NAME}ANSI颜色代码如${Ansi.GREEN}(用于着色)${AnsiColor.NAME}同上(用于着色)${AnsiBackground.NAME}ANSI背景色代码(用于着色)${AnsiStyle.NAME}ANSI样式如BOLD粗体(用于样式)一个功能丰富的banner.txt示例${Ansi.GREEN}${Ansi.RESET} ${Ansi.BRIGHT_YELLOW} ___ ___ _ _ _ _ ___ ___ _ _${Ansi.RESET} ${Ansi.BRIGHT_YELLOW} | _ \/ __| || || \| |/ __|/ _ \| \| |${Ansi.RESET} ${Ansi.BRIGHT_YELLOW} | /\__ \ __ || . | (_ | (_) | . |${Ansi.RESET} ${Ansi.BRIGHT_YELLOW} |_|_\|___/_||_||_|\_|\___|\___/|_|\_|${Ansi.RESET} ${Ansi.GREEN}${Ansi.RESET} ${Ansi.CYAN}Application : ${application.title}${Ansi.RESET} ${Ansi.CYAN}Version : ${application.formatted-version}${Ansi.RESET} ${Ansi.CYAN}Spring Boot : ${spring-boot.version}${Ansi.RESET} ${Ansi.CYAN}Profile(s) : ${spring.profiles.active:default}${Ansi.RESET} ${Ansi.GREEN}${Ansi.RESET}这个Banner会显示一个黄色的ASCII艺术字这里用MY-APP举例下面用青色列出应用名、版本、Spring Boot版本和当前激活的Profile如果未设置则显示default。${Ansi.RESET}用于重置颜色防止后续的日志也被着色。3.3 创建图像Banner如果你想使用公司或项目的Logo可以将其制作为Banner。准备一张图片格式支持GIF、JPG或PNG。为了获得较好的转换效果建议图片背景简洁、对比度高。将图片放入src/main/resources/目录并命名为banner.gif、banner.jpg或banner.png例如banner.png。根据需要在配置文件中调整图像转换参数。例如如果你的Logo是深色背景浅色图案可能需要设置spring.banner.image.inverttrue。启动应用Spring Boot会自动将图片转换为ASCII字符画并打印。实操心得图像Banner的转换效果非常依赖原图质量和参数设置。复杂的彩色图片转换出来可能是一团乱码。我个人的经验是使用单色、线条简单的Logo并反复调整width和height参数比如从默认的76调整到50或100直到在控制台获得清晰可辨的效果。pixelmodeBLOCK使用块状字符有时比TEXT使用文本字符效果更好可以都试试。4. 进阶玩法与多环境配置基本的替换已经能满足大部分需求但如果你想玩点更花的或者需要让Banner根据环境开发、测试、生产显示不同内容下面的技巧就派上用场了。4.1 基于Spring Profiles的差异化Banner这是非常实用的一个功能。你可以为不同的环境准备不同的Banner文件。命名规则创建以banner-profile.txt格式命名的文件。例如banner-dev.txt(用于开发环境)banner-test.txt(用于测试环境)banner-prod.txt(用于生产环境)放置位置将这些文件同样放在src/main/resources/目录下。激活Profile当启动应用时通过--spring.profiles.activedev参数激活dev环境。加载逻辑Spring Boot会优先加载与当前激活Profile对应的Banner文件如banner-dev.txt。如果找不到则回退到通用的banner.txt。示例banner-dev.txt内容可以活泼一点包含开发者的名字或提示“开发环境数据随时重置”。${Ansi.BRIGHT_GREEN} DEVELOPMENT ENVIRONMENT (Debug Mode: ON) ${Ansi.RESET}banner-prod.txt内容则需要严肃稳重突出版本号和警告信息。${Ansi.BRIGHT_RED} !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! PRODUCTION ENVIRONMENT Version: ${application.version} Handle with CARE! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ${Ansi.RESET}这样仅仅通过启动日志你就能立刻明确当前运行的是哪个环境避免误操作。4.2 编程式自定义Banner如果你需要极致的灵活性比如Banner内容需要从数据库读取或者根据复杂的逻辑动态生成那么可以通过实现Banner接口以编程方式设置。创建一个类实现org.springframework.boot.Banner接口。该接口只有一个方法printBanner。在printBanner方法中你可以通过PrintStream对象向控制台输出任何内容。在主启动类中通过SpringApplication.setBanner(...)方法设置你的自定义Banner实现。示例一个动态显示启动时间的Bannerimport org.springframework.boot.Banner; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.core.env.Environment; import java.io.PrintStream; import java.time.LocalDateTime; import java.time.format.DateTimeFormatter; SpringBootApplication public class MyApplication { // 自定义Banner实现类 static class DynamicBanner implements Banner { private static final DateTimeFormatter FORMATTER DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss); Override public void printBanner(Environment environment, Class? sourceClass, PrintStream out) { String appName environment.getProperty(spring.application.name, MyApp); String time LocalDateTime.now().format(FORMATTER); out.println(); out.println(╔══════════════════════════════════════╗); out.println(║ appName is BOOTING! ║); out.println(║ Startup Time: time ║); out.println(╚══════════════════════════════════════╝); out.println(); } } public static void main(String[] args) { SpringApplication app new SpringApplication(MyApplication.class); // 设置自定义Banner app.setBanner(new DynamicBanner()); app.run(args); } }这种方式赋予了Banner无限的可能性但代价是增加了代码复杂度。除非有强烈需求否则建议优先使用配置文件的方式。5. 常见问题、踩坑实录与最佳实践自定义Banner的过程看似简单但也藏着一些“坑”。下面是我在实践中总结的几个典型问题和解决方案。5.1 Banner不显示或显示乱码问题描述配置了banner.txt但启动时依然显示默认的Spring Banner或者显示一堆乱码。排查思路与解决检查文件位置和名称这是最常见的原因。确保文件名为banner.txt全小写无拼写错误并且放在src/main/resources/目录的根下而不是子目录里。如果你使用了spring.banner.location自定义路径请仔细检查路径是否正确。可以使用classpath:前缀指定类路径或file:前缀指定绝对路径。检查Banner模式确认spring.main.banner-mode没有被设置为off。如果是log模式Banner会输出到日志文件而不是控制台请检查日志文件。字符编码问题如果Banner内容包含中文或特殊字符确保你的banner.txt文件保存的编码是UTF-8无BOM。IDE如IntelliJ IDEA、Eclipse通常可以在文件属性或设置中查看和修改编码。在Windows记事本中另存为时选择“UTF-8”编码。图像Banner转换失败如果使用的是图片Banner乱码可能是图片转换效果不佳。尝试调整spring.banner.image.width/height或换用更简单的图片。也可以尝试将spring.banner.image.pixelmode改为BLOCK。5.2 环境变量占位符不生效问题描述在banner.txt中使用了${application.version}等占位符但启动时显示的是原样字符串${application.version}没有被替换。排查思路与解决检查项目版本信息${application.version}依赖于Maven的pom.xml或Gradle的build.gradle中定义的版本号。请确保你的构建文件中有正确的version或version配置。对于多模块项目要检查启动模块的配置。检查属性名拼写确保占位符的拼写完全正确例如是${application.version}而不是${app.version}。使用spring-boot.version如果你只是想显示Spring Boot的版本使用${spring-boot.version}这个是Spring Boot内置的一定有效。自定义属性你甚至可以引用application.properties中定义的属性例如在配置文件中定义my.envdev然后在Banner中使用${my.env}。这非常有用。5.3 Banner输出影响日志布局或引发异常问题描述Banner打印后后续的日志格式错乱或者在集成某些日志框架时出现异常。排查思路与解决ANSI颜色代码重置这是一个关键点。如果你在Banner中使用了ANSI颜色如${Ansi.GREEN}务必在结束处使用${Ansi.RESET}。否则后续所有控制台输出的颜色都会被你最后使用的颜色覆盖导致日志难以阅读。与Logback/Log4j2的集成大多数情况下Banner打印在日志系统初始化之前所以一般不会有冲突。但如果你在Banner中使用了过于复杂的字符或编码而系统终端不支持可能会导致显示问题。确保Banner内容兼容纯文本终端。异常IllegalArgumentException在极少数情况下如果图片Banner的路径错误或文件损坏可能会在启动时抛出异常。检查spring.banner.image.location的配置和文件完整性。5.4 最佳实践总结根据多年的项目经验我总结了以下几点使用Banner的最佳实践信息实用化不要只放一个酷炫的ASCII艺术。将${application.title}、${application.version}、${spring.profiles.active}这些关键信息放入Banner。在微服务排查问题时一眼能看到服务名和版本效率提升巨大。环境差异化务必使用banner-profile.txt为不同环境配置不同的Banner。生产环境的Banner可以加上醒目的警告边框和颜色如红色防止在错误的环境执行操作。保持简洁Banner不宜过长通常控制在20行以内为宜。过长的Banner会淹没真正重要的启动日志和错误信息。版本化考虑将Banner文件也纳入版本控制。当应用版本升级时Banner中的版本号占位符会自动更新但Banner的样式和布局也应该与版本同步管理。团队统一在团队内部可以约定一个Banner的大致风格或包含信息的规范这样所有服务的启动日志看起来会非常统一和专业。自定义Banner是Spring Boot提供的一个“小甜点”功能它几乎不消耗任何性能却能在提升开发体验、辅助运维排查方面起到意想不到的效果。花上半小时为你的项目定制一个独一无二、信息丰富的启动画面这笔时间投资绝对值得。希望这篇从原理到实践从基础到进阶再到避坑指南的完整梳理能帮助你彻底掌握这个有趣又实用的技能。