Spring Boot整合Thymeleaf运行时页面CSS样式失效问题

问题现象 #

• 技术栈：Spring Boot + Thymeleaf，集成Spring Security、JPA、OpenAPI等组件
• 异常表现：项目以Spring Boot应用形式启动后，浏览器访问页面出现布局错乱；直接在Eclipse中右键index.html选择本地浏览器打开时，页面布局可正常渲染
• 参考材料：
  • 异常效果截图：
  • 预期正常效果截图：
  • 项目目录结构截图：
  • 页面CSS引入代码截图：
• 现有pom.xml配置：

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-rest</artifactId>
    </dependency>
    
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-security</artifactId>
    </dependency>
    
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-thymeleaf</artifactId>
    </dependency>
    <dependency>
        <groupId>org.thymeleaf.extras</groupId>
        <artifactId>thymeleaf-extras-springsecurity5</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.thymeleaf.extras</groupId>
        <artifactId>thymeleaf-extras-springsecurity5</artifactId>
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-devtools</artifactId>
        <scope>runtime</scope>
        <optional>true</optional>
    </dependency>
    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql-connector-java</artifactId>
        <scope>runtime</scope>
    </dependency>
    <dependency>
        <groupId>org.postgresql</groupId>
        <artifactId>postgresql</artifactId>
        <scope>runtime</scope>
    </dependency>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.springframework.security</groupId>
        <artifactId>spring-security-test</artifactId>
        <scope>test</scope>
    </dependency>
    
    <dependency>
        <groupId>io.jsonwebtoken</groupId>
        <artifactId>jjwt</artifactId>
        <version>0.9.1</version>
    </dependency>
    
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-ui</artifactId>
        <version>1.6.4</version>
    </dependency>
    
    <dependency>
        <groupId>org.apache.httpcomponents</groupId>
        <artifactId>httpclient</artifactId>
    </dependency>
    
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <configuration>
                <excludes>
                    <exclude>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok</artifactId>
                    </exclude>
                </excludes>
            </configuration>
        </plugin>
    </plugins>
</build>

问题根因 #

本地直接打开HTML走file协议，直接读取同目录下的CSS文件，不存在服务端路径映射、权限拦截逻辑，所以渲染正常。服务启动后访问布局错乱，本质是CSS等静态资源加载失败，两个核心诱因：

1. 静态资源引用路径写死为相对路径，未通过Thymeleaf语法处理，上下文路径变化时寻址失败
2. 引入了Spring Security依赖但未放行静态资源路径，所有静态资源请求被鉴权拦截，返回403/302而非实际CSS内容

修复方案 #

按顺序做以下检查和修改：

• 修正模板中静态资源的引用方式
  所有CSS、JS、图片等静态资源引入，不要写硬编码相对路径，统一使用Thymeleaf的@{}语法自动拼接上下文根路径，示例：

  <!-- 错误写法 -->
  <link rel="stylesheet" href="css/bootstrap.min.css">
  <!-- 正确写法，路径开头的/代表static资源根目录 -->
  <link rel="stylesheet" th:href="@{/css/bootstrap.min.css}">
  

• 配置Spring Security放行静态资源
  在Spring Security配置类中添加静态资源路径的放行规则，示例：

  @Configuration
  @EnableWebSecurity
  public class SecurityConfig extends WebSecurityConfigurerAdapter {
      @Override
      protected void configure(HttpSecurity http) throws Exception {
          http
              .authorizeRequests()
                  // 放行所有静态资源路径，根据实际目录调整即可
                  .antMatchers("/css/**", "/js/**", "/images/**", "/fonts/**", "/webjars/**").permitAll()
                  // 其余业务接口的鉴权规则保留原有逻辑
                  .anyRequest().authenticated()
              // 表单登录、csrf等其他配置按业务需求保留
              ;
      }
  }
  

• 目录结构校验
  确认所有静态资源存放在src/main/resources/static目录下的对应子文件夹中，不要把CSS/JS等文件放到templates目录下——templates是Thymeleaf模板的存储目录，Spring Boot不会将该目录下的文件作为静态资源对外映射。
• 冗余配置清理
  pom.xml中重复引入了2次thymeleaf-extras-springsecurity5依赖，删掉其中一个即可，重复依赖不会影响功能但会增加构建冗余。

内容的提问来源于stack exchange，提问作者Count