Spring Boot启动时如何自定义Banner横幅并显示专属Logo

Spring Boot应用在启动时，控制台打印的第一段内容就是Banner横幅。默认情况下，它会展示Spring的绿色字符画以及Spring Boot的版本信息。这个行为并不是写死在日志框架里的，而是Spring Boot提供的一个可扩展点。只要在正确的位置放置资源文件，或者注册一个Banner接口实现类，就可以把启动横幅替换成项目自己的Logo、名称、版本或者任意文本。对于需要区分环境或多模块部署的应用来说，自定义Banner还能帮助开发者在日志流中快速识别当前启动的是哪个服务。

Spring Boot Banner的默认输出机制

Spring Boot在启动流程中会通过SpringApplication类的run方法触发banner打印。具体来说，SpringApplication会在环境准备完成之后、容器刷新之前，查找是否存在Banner接口的实现类。如果没有找到自定义实现，它会回到默认的SpringBootBanner，输出那个经典的Spring字符画。这个查找过程遵循一定的资源位置约定，classpath根目录下的banner.txt文件就是最常用的入口。

默认横幅的输出模式由spring.main.banner-mode属性控制，可以设置为console、log或者off。console表示打印到标准输出，log表示写入日志文件，off表示完全关闭。在实际项目中，如果应用运行在无交互的服务器环境，有时会因为日志采集系统重复收集控制台内容而选择把banner输出到log，或者直接关闭。banner-mode默认是console，因此大多数开发者第一次看到启动日志时，会先看到一段Spring符号。

除了banner.txt，Spring Boot还支持其他命名约定。classpath根目录下如果同时存在banner.txt和banner.png，Spring Boot会优先使用图片文件。图片会被转换成ASCII字符，并叠加颜色输出。对于文本横幅，可以通过banner.location指定一个非标准位置，例如classpath:config/banner.txt。需要注意的是，如果使用banner.location，Spring Boot不会再自动查找banner.txt，这一点在配置时容易忽略。

使用banner.txt实现静态字符横幅

最简单的自定义方式是在src/main/resources目录下新建banner.txt文件。文件内容会原样输出到控制台，因此可以直接把设计好的ASCII字符画粘贴进去。下面是一个简单的示例，输出项目名称和一行分隔线。这个文本可以在打包后随classpath一起分发，不依赖外部配置。

====================================
  MY PROJECT
  Version: 1.0.0
====================================

banner.txt不只是纯文本，Spring Boot还内置了一些占位符变量。常见的变量包括${spring-boot.version}、${spring-boot.formatted-version}、${application.title}和${application.version}。这些占位符的值来自环境配置，application.title对应spring.application.name，application.version对应spring.application.version。比如下面这段内容能让横幅动态显示应用名和版本，而不用修改字符画本身。

${spring-boot.formatted-version}
------------------------------------
Application: ${application.title}
Version: ${application.version}
------------------------------------

如果希望在终端中显示彩色横幅，可以使用ANSI颜色占位符。Spring Boot支持${AnsiColor.BRIGHT_RED}、${AnsiColor.GREEN}、${AnsiColor.YELLOW}等颜色常量，以及${AnsiStyle.BOLD}、${AnsiStyle.FAINT}等样式。颜色占位符需要放在文本之前，并且可以使用${AnsiColor.DEFAULT}恢复默认颜色。需要注意的是，ANSI颜色只有在支持ANSI转义序列的终端中才会正常显示，某些Windows控制台可能需要额外启用ANSI支持。

字符编码也是自定义banner时经常遇到的问题。如果字符画包含中文或特殊符号，需要确保banner.txt文件以UTF-8编码保存，并且可以在application.properties中设置banner.charset=UTF-8。如果文件编码与JVM默认编码不一致，控制台可能会出现乱码。建议在团队协作中统一编码规范，避免因为操作系统不同导致banner显示异常。

通过代码实现Banner接口动态生成横幅

对于需要根据不同环境输出不同内容的场景，静态banner.txt无法满足需求。这时可以实现org.springframework.boot.Banner接口，重写printBanner方法。这个方法的签名包含Environment、Class> sourceClass和PrintStream out三个参数，开发者可以从Environment中读取激活的Profile、自定义属性或者系统参数，然后通过out打印任意内容。下面是一个动态读取应用名称和环境的实现示例。

import java.io.PrintStream;
import org.springframework.boot.Banner;
import org.springframework.core.env.Environment;

public class CustomBanner implements Banner {

    @Override
    public void printBanner(Environment environment, Class<?> sourceClass, PrintStream out) {
        String appName = environment.getProperty("spring.application.name", "unknown-app");
        String profile = String.join(",", environment.getActiveProfiles());
        out.println("======================================");
        out.println("  " + appName.toUpperCase());
        out.println("  ACTIVE PROFILE: " + (profile.isEmpty() ? "default" : profile));
        out.println("======================================");
    }
}

要让这个实现生效，有两种注册方式。第一种是在SpringApplication对象上调用setBanner方法，这种方式适合Spring Boot应用入口比较固定的情况。第二种是把CustomBanner声明为Spring容器中的Bean，Spring Boot会优先查找类型为Banner的Bean并使用它。如果同时存在banner.txt文件和Banner Bean，代码实现的优先级更高。下面是通过入口类设置Banner的代码。

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication app = new SpringApplication(DemoApplication.class);
        app.setBanner(new CustomBanner());
        app.run(args);
    }
}

代码方式的好处是灵活性高，可以读取数据库配置、远程配置中心或者环境变量中的内容，动态生成横幅。例如在微服务架构中，每个实例启动时可以在横幅中打印IP地址、端口号和实例标识，这样在滚动发布或排查问题时非常直观。缺点是需要编写Java代码，并且如果项目中有多个SpringApplication入口，需要分别设置，维护起来比一个banner.txt文件稍显繁琐。

图片横幅与关闭横幅的配置方式

除了文本和代码，Spring Boot还支持使用图片作为横幅。将名为banner.gif、banner.jpg或banner.png的图片放在classpath根目录，Spring Boot会自动将图片转换为ASCII字符输出。图片转换后的效果受到终端宽度、字符集和颜色深度影响，通常适合简单的Logo或几何图形。如果图片内容复杂，ASCII效果可能不够清晰。可以通过banner.image.width和banner.image.height调整输出宽度和高度，也可以通过banner.image.invert反转颜色。

图片横幅在日志文件或非彩色终端中的可读性通常不如文本横幅。如果团队主要使用文本日志分析工具，建议优先使用banner.txt。对于需要展示品牌标识的场景，可以在本地开发时使用图片横幅，在生产环境使用文本或直接关闭，以减少日志文件体积。关闭横幅最简单的方式是在application.properties中设置spring.main.banner-mode=off，或者在application.yml中写同样的配置。

spring:
  main:
    banner-mode: off

如果想要保留日志输出但不在控制台显示，可以将banner-mode设置为log。这样横幅会写入日志文件，而不会污染控制台输出。需要注意的是，日志模式依赖日志框架已经完成初始化，因此横幅可能不会出现在日志文件的最开头。无论选择哪种模式，自定义横幅都应该被视为启动信息的一部分，而不是业务日志。合理使用Banner能在开发阶段提供清晰的启动反馈，同时不会对应用性能产生影响。

Spring Boot Banner自定义横幅启动横幅修改时间：2026-09-30 01:27:06