Thymeleaf、IntelliJ与Spring Boot无法正确加载CSS文件问题排查求助

我之前也踩过类似的坑，咱们一步步拆解可能导致这个问题的根源：

• 路由 fallback 配置冲突
  很多后端框架（比如Spring Boot+Thymeleaf）会把未匹配到的请求默认转发到首页。如果你的CSS文件路径没有被服务器识别为静态资源，就会被当成未匹配的路由，直接返回templates/index.html的内容。比如配置类里设置了forward:/index.html作为404 fallback，或者用@ControllerAdvice统一处理未找到的请求时跳转到首页，都会触发这个问题。

• 静态资源映射配置错误
  先检查静态资源的存放位置：比如Spring Boot默认会从src/main/resources/static、public目录加载静态资源，如果你的CSS文件误放到了templates目录下，服务器会把它当成模板文件处理，而不是静态资源。另外如果自定义了WebMvcConfigurer的addResourceHandlers方法，要确保路径映射正确，比如：

  @Override
  public void addResourceHandlers(ResourceHandlerRegistry registry) {
      registry.addResourceHandler("/css/**")
              .addResourceLocations("classpath:/static/css/");
  }
  

  这里的路径如果写错，会导致服务器找不到CSS文件，进而触发首页转发逻辑。

• 浏览器或服务器缓存干扰
  有时候浏览器会缓存旧的响应，哪怕你修复了配置，还是会返回之前的HTML内容。可以尝试用Ctrl+Shift+R强制刷新页面，或者给CSS请求加版本号（比如/css/style.css?v=20240520）来绕过缓存。如果是服务器端缓存，也需要清理对应的缓存文件。

• 路径或文件名拼写错误
  检查HTML里引用CSS的路径是否和实际文件路径一致，比如HTML里写的是./css/style.css，但实际文件是./css/Style.css（Linux服务器区分大小写），或者路径多了/少了层级，导致服务器找不到文件，最终返回首页。

• 反向代理服务器配置问题
  如果用了Nginx之类的反向代理，检查配置是否把所有请求都转发到了首页路由。比如Nginx里如果有这样的配置：

  location / {
      try_files $uri $uri/ /index.html;
  }
  

  会导致所有不存在的文件请求都返回index.html，包括你的CSS文件。需要调整配置，让静态资源请求直接返回文件：

  location /css/ {
      root /path/to/your/static/files;
  }
  location / {
      try_files $uri $uri/ /index.html;
  }
  

你之前新建项目能解决，大概率是新项目默认的静态资源配置是正确的，而旧项目的配置被修改过或者路径出了问题。按照上面的步骤逐一排查，应该能找到问题的根源。

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