一、核心概念

Spring Boot 默认提供了一套简单而强大的机制来处理静态资源（如 CSS、JavaScript、图片、字体文件等），无需额外配置即可满足大部分需求。其核心基于 ResourceHttpRequestHandler 和 ResourceProperties。

关键概念

  1. 静态资源位置 (Static Resource Locations):

    • Spring Boot 会自动从类路径 (classpath) 下的特定目录查找静态资源文件。
    • 默认位置（按优先级顺序）：
      • classpath:/META-INF/resources/
      • classpath:/resources/
      • classpath:/static/ (最常用)
      • classpath:/public/
    • 你也可以通过配置 spring.web.resources.static-locations 来添加或覆盖这些位置。
    • 注意： src/main/webapp 目录（传统 WAR 项目结构）不会被自动包含，除非你使用 spring-boot-starter-tomcat 并启用 server.servlet.context-path，或者显式配置。建议使用上述类路径目录。

  2. URL 映射 (URL Mapping):

    • 默认情况下，所有在上述目录中的文件都可以通过 / 根路径直接访问。
    • 例如：classpath:/static/css/style.css 可以通过 http://localhost:8080/css/style.css 访问。
    • 你可以通过 spring.mvc.static-path-pattern 配置一个前缀，比如 /static/**，这样访问路径就变成了 http://localhost:8080/static/css/style.css。

  3. ResourceHttpRequestHandler:

    • 这是 Spring MVC 内部处理静态资源请求的组件。当一个请求无法被任何 @Controller 处理时，Spring MVC 会尝试让 ResourceHttpRequestHandler 来处理，它会按照配置的 static-locations 去查找文件。

  4. 欢迎页 (Welcome Page):

    • Spring Boot 支持 index.html 作为欢迎页。如果在任何静态资源目录下存在 index.html，访问应用根路径 (/) 时会自动显示它。

  5. WebJars:

    • WebJars 是将前端库（如 jQuery, Bootstrap, Vue.js）打包成 JAR 文件的方式，方便通过 Maven/Gradle 管理依赖。
    • WebJars 的内容位于 classpath:/META-INF/resources/webjars/，因此也符合默认的静态资源查找规则。

二、操作步骤（非常详细）

步骤 1：准备静态资源文件

  1. 创建资源目录：

    • 在你的 Spring Boot 项目中，导航到 src/main/resources 目录。
    • 在此目录下创建一个或多个用于存放静态资源的子目录。最常用的是 static。
    • 推荐结构： 
      src/
└── main/
    └── resources/
        ├── static/               # 主静态资源目录
        │   ├── css/              # CSS 文件
        │   │   └── style.css
        │   ├── js/               # JavaScript 文件
        │   │   └── app.js
        │   ├── images/           # 图片文件
        │   │   └── logo.png
        │   └── favicon.ico       # 网站图标 (放在根目录或 images/)
        ├── templates/            # Thymeleaf 模板 (如果使用)
        │   └── home.html
        └── application.properties # 配置文件
    • 你也可以选择 public 或 resources 目录，但 static 是约定俗成的首选。

  2. 放入文件：

    • 将你的 CSS 文件放入 static/css/。
    • 将你的 JavaScript 文件放入 static/js/。
    • 将你的图片文件放入 static/images/。
    • 将 favicon.ico 放在 static/ 根目录或 static/images/。

步骤 2：在 HTML 模板或页面中引用

场景 A：使用 Thymeleaf 模板引擎 (最常见)

  1. 创建 Thymeleaf 模板 (src/main/resources/templates/home.html):

    <!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>Home</title>
    <!-- 1. 引用 CSS 文件 -->
    <link th:href="@{/css/style.css}" rel="stylesheet" type="text/css">
    <!-- 2. 引用 WebJar 中的 Bootstrap CSS (假设已添加依赖) -->
    <link th:href="@{/webjars/bootstrap/css/bootstrap.min.css}" rel="stylesheet">
</head>
<body>
    <h1>Welcome!</h1>
    <!-- 3. 引用图片 -->
    <img th:src="@{/images/logo.png}" alt="Logo" width="200">
    <!-- 4. 引用 JS 文件 -->
    <script th:src="@{/js/app.js}"></script>
    <!-- 5. 引用 WebJar 中的 jQuery JS -->
    <script th:src="@{/webjars/jquery/jquery.min.js}"></script>
</body>
</html>
    • 关键： 使用 th:href="@{/...}" 和 th:src="@{/...}"。@{...} 是 Thymeleaf 的 URL 表达式，它会自动处理上下文路径（Context Path），确保链接正确。

  2. 创建控制器返回视图:

    import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;

@Controller
public class HomeController {

    @GetMapping("/") // 访问根路径
    public String home() {
        return "home"; // 返回模板名称 "home", 对应 home.html
    }
}

场景 B：直接访问纯 HTML 文件

  1. 将 HTML 文件放入 static 目录 (src/main/resources/static/index.html):

    <!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Static Index</title>
    <!-- 6. 直接使用相对路径或绝对路径引用 -->
    <link rel="stylesheet" href="/css/style.css"> <!-- 绝对路径 /css/style.css -->
    <link rel="stylesheet" href="css/style.css">  <!-- 相对路径 (相对于当前 HTML 文件) -->
</head>
<body>
    <h1>Static Page</h1>
    <img src="/images/logo.png" alt="Logo">
    <script src="/js/app.js"></script>
</body>
</html>
    • 注意： 因为 index.html 在 static/ 目录下，它的“位置”在 /。所以 /css/style.css 和 css/style.css 都能正确找到 static/css/style.css。

  2. 访问： 启动应用后，访问 http://localhost:8080/ 或 http://localhost:8080/index.html 即可看到页面。

步骤 3：使用 WebJars (可选但推荐)

  1. 添加 WebJar 依赖 (Maven pom.xml):

    <dependency>
    <groupId>org.webjars</groupId>
    <artifactId>bootstrap</artifactId>
    <version>5.3.2</version> <!-- 指定版本 -->
</dependency>
<dependency>
    <groupId>org.webjars</groupId>
    <artifactId>jquery</artifactId>
    <version>3.7.1</version>
</dependency>
<!-- 找到需要的 WebJar: https://www.webjars.org/ -->

  2. 在 HTML/Thymeleaf 中引用 (如上所示):

    • 路径为 /webjars/[artifactId]/[version]/... 或 /webjars/[artifactId]/... (WebJars 提供了版本号映射，通常可以省略具体版本号，由 /webjars-locator 处理)。
    • 在 Thymeleaf 中使用 th:href="@{/webjars/bootstrap/css/bootstrap.min.css}"。

步骤 4：自定义配置 (可选)

  1. 修改静态资源映射路径 (在 application.properties 中):

    # 让所有静态资源必须通过 /static/ 前缀访问
spring.mvc.static-path-pattern=/static/**
# 现在访问 style.css 需要 http://localhost:8080/static/css/style.css
# 注意：Thymeleaf 中的 @{/css/style.css} 仍然有效，因为它会映射到 /static/css/style.css

  2. 添加额外的静态资源位置 (在 application.properties 中):

    # 添加文件系统中的目录 (绝对路径)
spring.web.resources.static-locations=classpath:/static/,classpath:/public/,file:/opt/myapp/assets/
# 注意：覆盖了默认位置，所以需要手动包含 classpath 位置

  3. 禁用默认静态资源处理 (不推荐，除非有特殊需求):

    # 这会禁用所有默认的静态资源处理
# spring.web.resources.add-mappings=false

  4. 通过 Java 配置 (更灵活):

    import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class StaticResourceConfig implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 1. 自定义映射：将 /files/** 映射到文件系统目录
        registry.addResourceHandler("/files/**")
                .addResourceLocations("file:/path/to/uploaded/files/");

        // 2. 自定义映射：将 /assets/** 映射到另一个类路径目录
        registry.addResourceHandler("/assets/**")
                .addResourceLocations("classpath:/my-assets/");

        // 3. 注意：如果重写此方法，通常需要手动添加默认的映射，除非你想完全自定义
        // registry.addResourceHandler("/**")
        //         .addResourceLocations("classpath:/static/", "classpath:/public/");
    }
}
    • 重要： 如果你实现了 WebMvcConfigurer 并重写了 addResourceHandlers，默认的静态资源映射 (/**) 不会自动添加。你需要显式地调用 registry.addResourceHandler("/**").addResourceLocations(...) 并传入你想要的 locations（如 classpath:/static/, classpath:/public/ 等），或者只添加你自定义的映射。

三、常见错误

  1. 文件找不到 (404 Not Found):

    • 原因： 文件未放在正确的目录 (static, public, resources, META-INF/resources)；文件名或路径拼写错误；@ComponentScan 未扫描到配置类（极少见）；自定义 addResourceHandlers 时覆盖了默认映射且未手动添加。
    • 解决： 检查文件位置和名称；检查 spring.mvc.static-path-pattern 配置；如果使用 Java 配置 WebMvcConfigurer，确保 addResourceHandlers 中包含了默认的 /** 映射或你期望的映射。

  2. CSS/JS 不生效：

    • 原因： HTML 中引用路径错误（如 src="js/app.js" 但文件在 static/js/，且 HTML 在根路径）；浏览器缓存了旧文件；CSS/JS 文件本身有语法错误。
    • 解决： 使用开发者工具 (F12) 检查 Network 选项卡，确认资源是否 200 OK 加载；检查引用路径（推荐使用 Thymeleaf @{...} 或绝对路径 /js/app.js）；清除浏览器缓存或强制刷新 (Ctrl+F5)。

  3. favicon.ico 不显示：

    • 原因： 文件未放在 static/ 根目录或 static/images/；浏览器缓存了旧图标。
    • 解决： 将 favicon.ico 放在 src/main/resources/static/favicon.ico；清除浏览器缓存。

  4. WebJar 资源 404:

    • 原因： 未在 pom.xml/build.gradle 中正确添加依赖；依赖版本号错误；在 HTML 中引用的路径错误（如 artifactId 拼错）。
    • 解决： 检查依赖是否下载成功；在 target/classes/META-INF/resources/webjars/ (Maven) 或 build/resources/main/META-INF/resources/webjars/ (Gradle) 下确认文件结构；检查引用路径。

  5. 自定义配置后静态资源失效：

    • 原因： 在 application.properties 中设置了 spring.web.resources.static-locations 但遗漏了 classpath:/static/ 等默认位置；在 WebMvcConfigurer 的 addResourceHandlers 中未添加 /** 映射。
    • 解决： 确保 static-locations 包含所有需要的路径；在 Java 配置中显式添加默认映射。

四、注意事项

  1. 优先级： 当多个静态资源目录包含同名文件时，按 META-INF/resources/ > resources/ > static/ > public/ 的顺序，前面的优先级更高。
  2. src/main/webapp： 在 Spring Boot 中，除非特别配置（如使用 WarLauncher 或 server.servlet.context-path），src/main/webapp 目录不会被自动作为静态资源目录。建议使用 classpath:/static/。
  3. classpath: vs file:： classpath: 指向 JAR/WAR 包内的资源；file: 指向文件系统。注意权限和路径分隔符（Windows \ vs Unix /）。
  4. 上下文路径 (Context Path)： 如果应用部署在子路径下（如 http://example.com/myapp/），使用 Thymeleaf @{...} 或 HTML 中的绝对路径 /css/style.css 时，Spring 会自动处理上下文路径，确保链接正确 (/myapp/css/style.css)。相对路径 (css/style.css) 则基于当前页面 URL。
  5. index.html 优先级： index.html 会作为欢迎页，优先于其他控制器处理根路径请求。
  6. ResourceHttpRequestHandler 与 DispatcherServlet： 静态资源请求最终由 DispatcherServlet 分发给 ResourceHttpRequestHandler 处理。如果一个 @Controller 的 @RequestMapping 覆盖了静态资源路径（如 @RequestMapping("/")），它会优先匹配，阻止静态资源的访问。
  7. 安全性： 默认情况下，所有静态资源都是公开可访问的。如果需要保护某些资源，应将其移出静态目录，通过 @Controller 方法（添加安全注解如 @PreAuthorize）进行受控访问。

五、使用技巧

  1. Thymeleaf @{...} 表达式： 这是引用静态资源的最佳方式，因为它能自动处理上下文路径和 URL 编码。
  2. 版本化文件名 (Cache Busting):
    • 为了强制浏览器更新缓存的 CSS/JS 文件，可以在文件名中加入版本号或哈希值，如 app.v1.2.3.js 或 app.a1b2c3d.js。
    • 结合构建工具（如 Webpack, Maven 插件）自动生成带哈希的文件名。
    • 在 Thymeleaf 中动态引用： 
      <script th:src="@{/js/app.__version__.js}"></script> <!-- 使用占位符 -->
<!-- 或通过 Model 传递实际文件名 -->
<script th:src="${jsFileUrl}"></script>
  3. 使用 CDN： 对于常用的库（如 jQuery, Bootstrap），优先使用公共 CDN，可以加快加载速度并利用浏览器缓存。
  4. ResourceUrlEncodingFilter (Thymeleaf): 如果需要对静态资源 URL 进行编码（如包含特殊字符），Thymeleaf 通常已处理。此过滤器主要用于 JSP。
  5. WebMvcConfigurer 的灵活性： 使用 Java 配置可以实现复杂的映射逻辑，如将特定前缀映射到不同位置，或添加缓存控制。
  6. ResourceResolver 和 ResourceTransformer：
    • ResourceResolver: 可以自定义资源查找逻辑（如从数据库加载）。
    • ResourceTransformer: 可以在资源返回前进行转换，如：
      • CSS/JS 压缩 (Minification): 使用 CachingResourceTransformer 结合 ResourceUrlProvider 实现。
      • 版本化 URL: 通过 VersionResourceResolver 为 URL 添加版本戳（查询参数或文件名后缀）。
    • 示例 (Java 配置): 
      @Configuration
public class ResourceConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/static/**")
                .addResourceLocations("classpath:/static/")
                .resourceChain(true) // 启用资源链
                .addResolver(new VersionResourceResolver().addContentVersionStrategy("/**")); // 内容哈希版本策略
    }
}
      这会使 /static/js/app.js 的 URL 变成 /static/js/app-{hash}.js，实现完美的缓存控制。

六、最佳实践

  1. 使用 src/main/resources/static/ 目录： 这是社区标准，清晰明了。
  2. 组织好目录结构： 如 css/, js/, images/, fonts/ 等，便于管理。
  3. 优先使用 Thymeleaf @{...}： 在模板中引用资源，确保链接正确性。
  4. 利用 WebJars 管理前端依赖： 便于版本控制和依赖管理。
  5. 实现 Cache Busting： 通过文件名版本化或查询参数，解决浏览器缓存问题。
  6. 分离静态资源与模板： .html 模板放在 templates/，静态的 .html 页面（如果需要）放在 static/。
  7. 保持 static 目录内容公开： 不要将敏感文件（如配置文件、源码）放入其中。
  8. 使用构建工具处理前端资源： 对于复杂的前端项目，使用 Webpack, Vite, Gulp 等工具进行打包、压缩、版本化，然后将产物输出到 static 目录。
  9. 配置合理的缓存策略： 利用 HTTP 缓存头（Cache-Control）。
  10. 监控资源加载性能： 使用浏览器开发者工具分析加载时间。

七、性能优化

  1. GZIP/Brotli 压缩：

    • 启用服务器压缩，显著减小 CSS、JS、HTML 等文本资源的大小。
    # application.properties
server.compression.enabled=true
server.compression.mime-types=text/html,text/xml,text/plain,text/css,text/javascript,application/javascript,application/json
server.compression.min-response-size=1024 # 最小压缩大小
# Brotli (需要 Tomcat 10.1+ 或其他支持)
# server.compression.enabled=true
# server.compression.mime-types=... (同上)
# server.compression.brotli.enabled=true

  2. HTTP 缓存 (Cache-Control):

    • 为静态资源设置长缓存时间（如 1 年），配合 Cache Busting (文件名加哈希) 使用。
    • Java 配置示例： 
      @Configuration
public class CacheConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/static/**", "/webjars/**")
                .addResourceLocations("classpath:/static/", "classpath:/META-INF/resources/webjars/")
                .setCachePeriod(31536000) // 1 year in seconds
                .resourceChain(true)
                .addResolver(new VersionResourceResolver().addContentVersionStrategy("/**"));
    }
}
    • 这样，带哈希的 URL (app.a1b2c3d.js) 可以被长期缓存，而 HTML 模板中的引用会更新为新哈希，实现“永不缓存 HTML，永久缓存资源”。

  3. CDN (内容分发网络):

    • 将静态资源托管到 CDN，利用其全球节点加速访问，减轻源服务器压力。

  4. 资源压缩 (Minification):

    • 在构建阶段（使用 Webpack, UglifyJS, CSSNano 等）压缩 CSS 和 JS 文件，移除空格、注释，缩短变量名。

  5. 图片优化：

    • 使用合适的格式（WebP > JPEG/PNG）。
    • 压缩图片大小（使用工具如 ImageOptim, TinyPNG）。
    • 使用响应式图片 (srcset, sizes)。
    • 考虑懒加载 (loading="lazy")。

  6. 减少 HTTP 请求数：

    • 合并小的 CSS/JS 文件（但需权衡与并行下载和缓存粒度的关系）。
    • 使用 CSS Sprites（合并小图标）。
    • 内联关键 CSS (Critical CSS)。

  7. 利用 ResourceTransformer： 如上所述，使用 VersionResourceResolver 实现高效的缓存控制。

  8. 监控与分析：

    • 使用 Spring Boot Actuator 的 /metrics/http.server.requests 监控静态资源请求的延迟。
    • 使用 Lighthouse 或 PageSpeed Insights 分析前端性能。

总结： Spring Boot 的静态资源支持开箱即用，遵循约定优于配置原则。将资源放入 src/main/resources/static/ 目录，并通过 /path/to/file 访问是最简单的方式。使用 Thymeleaf 的 @{...} 表达式是引用资源的最佳实践。通过 WebJars 管理前端库依赖。为了最佳性能和用户体验，务必实施 GZIP 压缩 和基于 文件名版本化 (Cache Busting) 的 长缓存策略，并考虑使用 CDN。避免常见错误，如文件位置错误或自定义配置时覆盖默认映射。