SpringBoot 静态资源核心映射规则

SpringBoot 对静态资源的处理做了高度封装，核心围绕「默认资源位置」「访问路径映射」「自定义配置」三大维度设计，旨在简化静态资源（CSS/JS/ 图片 / 静态页面等）的访问与管理，以下是其核心映射规则的详细解析：

一、默认静态资源存放位置（优先级从高到低）

SpringBoot 启动时会自动扫描以下目录作为静态资源根路径，资源可直接通过「访问路径」访问，无需额外配置：

1. classpath:/META-INF/resources/（常用于第三方 jar 包的静态资源）
2. classpath:/resources/（项目核心静态资源目录）
3. classpath:/static/（最常用，默认推荐存放目录）
4. classpath:/public/（通用公共静态资源）

示例：在 classpath:/static/ 下存放 img/logo.png，可直接通过 http://localhost:8080/img/logo.png 访问。

二、默认访问路径映射规则

1. 基础映射：默认情况下，静态资源的访问路径为「/**」，即所有未被控制器（@Controller/@RestController）匹配的请求，都会尝试从上述静态资源目录查找。
   • 例如：请求 http://localhost:8080/js/index.js → 匹配 classpath:/static/js/index.js。
2. 欢迎页（首页）规则：SpringBoot 会自动查找静态资源目录下的 index.html 作为默认首页，访问 http://localhost:8080/ 时直接返回该文件。
3. favicon.ico 规则：自动查找静态资源目录下的 favicon.ico 作为网站图标，无需手动配置映射。

三、静态资源前缀配置（自定义访问路径）

若需给静态资源添加统一访问前缀（如 /static/**），可通过配置修改映射规则：

1. SpringBoot 2.x/3.x 配置（application.yml）

yaml

spring:
  web:
    resources:
      # 静态资源访问前缀（需加/**）
      static-path-pattern: /static/**
      # 自定义静态资源根目录（可追加多个）
      locations: [classpath:/my-static/, classpath:/static/]

 

效果：访问 http://localhost:8080/static/img/logo.png → 匹配 classpath:/my-static/img/logo.png（优先级更高）或 classpath:/static/img/logo.png。

四、静态资源缓存与版本控制

1. 默认缓存策略：SpringBoot 对静态资源默认开启缓存（通过响应头 Cache-Control），可通过配置调整缓存时长：

yaml

 

spring:
  web:
    resources:
      cache:
        # 缓存有效期（单位：秒）
        period: 3600

 

2. 版本控制（防止缓存失效）：
   • 方式 1：手动添加版本号（如 js/index.js?v=1.0）；
   • 方式 2：配置资源哈希版本（需结合 WebMvcConfig 自定义）。

五、静态资源禁用 / 优先级说明

1. 禁用静态资源映射：若无需静态资源功能，可通过配置关闭：

yaml

 

spring:
  web:
    resources:
      add-mappings: false

 

2. 控制器优先级高于静态资源：若控制器映射路径（如 @GetMapping("/img/logo.png")）与静态资源路径冲突，优先执行控制器逻辑，不会访问静态资源。

六、核心底层逻辑（补充）

SpringBoot 静态资源映射的核心由 WebMvcAutoConfiguration 自动配置类实现，默认注册 ResourceHttpRequestHandler 处理静态资源请求，若自定义 WebMvcConfigurer 并重写 addResourceHandlers 方法，会覆盖默认规则（可实现更灵活的映射）。

自定义资源映射示例（代码层面）

java

 

运行

 

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 映射本地磁盘目录到访问路径
        registry.addResourceHandler("/disk/**")
                .addResourceLocations("file:D:/static/");
    }
}

 

效果：访问 http://localhost:8080/disk/img/photo.jpg → 匹配本地 D:/static/img/photo.jpg。