如何通过 Spring Boot 的 Banner 扩展实现在系统启动时输出环境版本信息与关键依赖项检查报告-java教程-PHP中文网

在 banner.txt 中嵌入动态变量需依赖 manifest.mf 中的对应字段（如 implementation-version），仅当使用 spring-boot-maven-plugin 正确配置 archive 时，${application.version} 等占位符才生效；ide 直接运行主类不解析占位符；图片 banner 不支持变量替换，动态内容须通过实现 banner 接口或构建期生成实现。

如何通过 spring boot 的 banner 扩展实现在系统启动时输出环境版本信息与关键依赖项检查报告

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 中插件配置包含 <archive><manifest><adddefaultimplementationentries>true</adddefaultimplementationentries></manifest></archive>
${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() 才会懂。