Spring Boot Banner 扩展实现启动信息输出

Spring Boot 的 Banner 不仅是启动时的装饰性文字，更是反映应用真实运行状态的重要窗口——但动态变量（如 `${application.version}`）仅在打包为可执行 JAR 并通过 Launcher 启动时生效，IDE 直接运行会原样输出；图片 Banner 完全不支持变量替换，而复杂运行时检查（如 Redis 是否启用、MySQL 连接池健康状态）更无法靠 `banner.txt` 实现，必须通过自定义 `Banner` 接口在启动早期安全地访问 `Environment` 和类加载器等有限上下文；真正可靠的方案是：构建期预处理文本 Banner、代码中精准控制输出时机与内容、避开未初始化 Bean 的陷阱，并理解 Spring Boot 启动流程中那些文档未明说却决定成败的关键边界。

banner.txt 里怎么嵌入动态变量

直接写 ${application.version} 或 ${spring-boot.version} 是最常用的方式，但这些占位符只在 Spring Boot Launcher 启动（如 jar 包执行）时生效，IDE 直接 run 主类会显示原样字符串。真正起作用的前提是：MANIFEST.MF 文件中存在对应字段 —— 比如 Maven 打包时需启用 spring-boot-maven-plugin 的 archive 配置，否则 ${application.version} 始终为空。

常见错误现象：启动后看到 ${application.version} 原样输出，不是实际版本号。

• 检查 target/classes/META-INF/MANIFEST.MF 是否含 Implementation-Version: 1.2.3
• 确保 pom.xml 中插件配置包含 true
• ${application.formatted-version} 会自动加前缀 v，而 ${spring-boot.formatted-version} 同理，但注意它读取的是 Spring Boot 自身版本，不是你的应用版本

想显示依赖版本或运行时检查结果，不能只靠 banner.txt

文本 Banner 是静态资源，banner.txt 本身不支持 Java 表达式或逻辑判断。若要在启动时输出「当前环境是否启用 Redis」「MySQL 连接池是否健康」这类检查报告，必须绕过纯文本路径，改用代码方式实现 Banner 接口。

核心做法：实现 org.springframework.boot.Banner，重写 printBanner() 方法，在其中调用 Environment、ApplicationContext 或自定义 HealthIndicator —— 注意此时 ApplicationContext 尚未完全刷新，只能访问已加载的 Bean（如 Environment、ResourceLoader），不能调用 @Service 或 @Repository。

• 不要在 printBanner() 中尝试注入 JdbcTemplate 或发起 HTTP 请求，会抛 IllegalStateException
• 可用的检查项举例：environment.getProperty("spring.profiles.active")、environment.containsProperty("redis.host")、ClassUtils.isPresent("redis.clients.jedis.Jedis", getClass().getClassLoader())
• 输出到 PrintStream 时建议统一用 System.out，避免日志框架尚未初始化导致乱码或丢失

图片 Banner 和文本 Banner 能否同时生效

可以，但顺序固定：Spring Boot 会先尝试加载 banner.gif/banner.jpg/banner.png，成功则输出图片转 ASCII；失败才 fallback 到 banner.txt。两者不会叠加，更不会并行。

容易踩的坑是误以为图片 Banner 支持占位符替换 —— 实际上图片 Banner 是纯二进制资源，${...} 在图片里毫无意义。所有动态内容（比如环境名、Git 提交 ID）必须通过代码 Banner 实现，或者提前在构建阶段生成带变量的 banner.txt（例如用 Maven Resources Plugin + filtering）。

• 若项目用了多模块，确保 banner.txt 在最终可执行 jar 的 BOOT-INF/classes/ 根路径下，而非子模块 resources 中
• 图片 Banner 对宽高比敏感，过宽的 PNG 可能被截断或换行错乱，推荐尺寸 ≤ 80 字符宽 × 25 行高
• 使用 spring.banner.image.width 和 spring.banner.image.height 可强制缩放，但可能失真

关闭默认 Banner 并接管全部输出逻辑的关键点

设置 spring.main.banner-mode=off 会彻底跳过 Banner 加载流程，连你自定义的 Banner 实现也不会触发。正确做法是保留默认流程，仅替换 Banner 实例 —— 在 SpringApplication 构造后、run() 前调用 setBanner()。

最稳妥的注册时机是创建 SpringApplication 的地方（比如主类 main() 方法内），而不是靠 @Bean 注入，因为 Banner 实例必须在 prepareEnvironment 阶段前就位。

• 不要在 @Configuration 类里声明 @Bean public Banner myBanner() —— Spring Boot 不会识别这个 Bean
• 正确姿势：SpringApplication app = new SpringApplication(MyApp.class); app.setBanner(new MyCustomBanner()); app.run(args);
• 如果用 Spring Boot 3.x+，注意 Banner 接口已标记为 @Deprecated，但目前仍有效；替代方案是监听 ApplicationStartingEvent，不过此时无法控制输出位置和格式

真正难的不是拼出一行带颜色的字符串，而是让 Banner 输出的内容既反映真实运行态，又不破坏启动流程的稳定性。比如检查数据库连接，得确认 DataSource 已创建但事务管理器还没初始化 —— 这种边界，文档不会写，只有 debug 过 SpringApplication.prepareEnvironment() 才会懂。

好了，本文到此结束，带大家了解了《Spring Boot Banner 扩展实现启动信息输出》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！