麻雀窝 Sparrow Zoo

Spring Boot 静态资源 URL 查找:分类、优先级与访问方式

梳理 Spring Boot 默认的 URL 查找流程与处理器优先级,分类说明静态资源的存放位置与访问方式,并用表格对比;强调按默认优先级使用、不强行修改以保障安全。

后端开发者(Spring Boot 2.x / 3.x)发布于 更新于
URL 查找优先级1 · Controller 映射2 · WebJars /webjars/**3 · 静态资源 /**4 · 欢迎页 index.html默认优先 · 安全优先
阅读目录

结论先行

Spring Boot 处理一个 URL 请求时,遵循固定的优先级顺序:控制器映射(@Controller) 最高,其次是 WebJar(/webjars/**),再是 静态资源(/**),最后是 欢迎页(index.html)。同一路径下,优先级高者胜出。

静态资源按存放位置分四类,查找顺序固定为 classpath:/META-INF/resources/ → classpath:/resources/ → classpath:/static/ → classpath:/public/;按访问路径分三类:默认的 /** 静态资源、/webjars/** 依赖库、根路径 / 的欢迎页。

这些默认优先级是 Spring Boot 团队为 安全 反复权衡的结果:模板目录与 classpath 上的敏感文件(配置文件、私钥、.class)默认不可被 /** 访问,控制器始终优先于静态文件,避免业务路由被同名静态文件遮蔽。因此,除非确有明确需求,否则 不要强行修改默认优先级。

问题背景

把静态文件放进 Spring Boot 项目后,最常见的困惑有两个:一是「文件该放哪个目录」,二是「为什么有时 404、有时又和 Controller 撞车」。例如把 index.html 放错目录访问不到,或者定义了 @GetMapping("/about") 之后,static/about.html 突然「失效」。

要讲清楚这些,先认识三个概念:

DispatcherServlet
Spring MVC 的核心分发器,所有 HTTP 请求先到它,再由它按顺序交给不同的「处理器映射」。
HandlerMapping
负责根据 URL 找到处理器。Spring Boot 注册了多个,按优先级排序,靠前的先匹配。
静态资源 / WebJar
不经过业务代码、直接返回文件内容的资源;WebJar 是把前端库打包成 JAR、放在 classpath 上供引用的约定。

理解了「优先级」和「位置分类」,上面的困惑就迎刃而解。

详细内容

URL 查找的总体流程与处理器优先级

请求进入 DispatcherServlet 后,会按顺序遍历一组 HandlerMapping,第一个能匹配到 URL 的映射决定由谁处理。默认优先级从高到低为:

  1. 控制器映射(RequestMappingHandlerMapping)——处理 @Controller / @RequestMapping 定义的路由。
  2. 资源处理器(SimpleUrlHandlerMapping)——处理静态资源与 WebJar。
  3. 欢迎页(WelcomePageHandlerMapping)——只处理根路径 /,返回 index.html。

关键结论:控制器永远优先于静态资源。若同时存在 @GetMapping("/about") 与静态文件 static/about.html,访问 /about 命中控制器;反之,静态文件也无法「抢走」已有控制器的路由。

URL 查找的处理器优先级(从高到低)
优先级处理器典型对象
1(最高)RequestMappingHandlerMapping@Controller 方法
2SimpleUrlHandlerMappingWebJar /webjars/**
3SimpleUrlHandlerMapping静态资源 /**
4(最低)WelcomePageHandlerMappingindex.html(仅 /)

静态资源的四个默认目录

Spring Boot 默认从以下 classpath 位置按顺序查找静态资源(spring.web.resources.static-locations 的默认值):

  1. classpath:/META-INF/resources/(优先级最高)
  2. classpath:/resources/
  3. classpath:/static/
  4. classpath:/public/(优先级最低)

以 Maven 项目为例,这些目录对应 src/main/resources/ 下的同名子目录。请求 /css/app.css 时,Spring 会依次在这些目录下找 css/app.css,第一个命中的生效;同名文件放在多个目录时,靠前的目录胜出。

默认静态目录的查找顺序(同名文件靠前目录胜出)
顺序classpath 位置Maven 对应目录
1classpath:/META-INF/resources/src/main/resources/META-INF/resources/
2classpath:/resources/src/main/resources/resources/
3classpath:/static/src/main/resources/static/
4classpath:/public/src/main/resources/public/

打包成 WAR 时,还会附带 Servlet 容器根目录 / 作为最低优先级兜底。

WebJar 的专用路径

WebJar 把 jQuery、Bootstrap 等前端库打包成 JAR,把静态资源放在 JAR 的 META-INF/resources/webjars/ 下,随依赖一起进入 classpath。

Spring Boot 为它预留了专用路径 /webjars/**(spring.mvc.webjars-path-pattern 的默认值),映射到 classpath:/META-INF/resources/webjars/。例如引入 org.webjars:jquery:3.6.0 后,可访问:

code
/webjars/jquery/3.6.0/jquery.min.js

WebJar 与普通静态资源路径不重叠(/webjars/** 更具体,先于 /** 匹配),互不干扰。若要省去版本号,可额外引入 webjars-locator-core,用 /webjars/jquery/jquery.min.js 访问——这是可选增强,非默认行为。

欢迎页与 favicon

请求根路径 / 时,若没有控制器处理,Spring Boot 会在各静态位置查找 index.html 作为欢迎页返回;若有 @Controller 处理 /,控制器仍优先。

favicon.ico 同样作为普通静态资源处理,放进任一静态目录即可通过 /favicon.ico 访问(新版 Spring Boot 已不再需要单独配置)。

分类与访问方式总表

把上面的分类汇总成一张总表,按查找优先级从高到低排列:

静态资源分类与访问方式对照
类别存放位置访问 URL优先级
控制器Java @Controller任意(@GetMapping)最高
WebJarclasspath:/META-INF/resources/webjars//webjars/{name}/{version}/…高
静态资源META-INF/resources / resources / static / public/**(如 /css/app.css)中
欢迎页任一静态目录下的 index.html/低

窄屏可左右滑动表格查看完整内容。

默认优先级的安全考量

这些默认值不是随意设定的,而是安全边界的一部分。理解这几点,就明白为什么「按默认优先级处理」是更稳妥的选择:

  • 模板不暴露:src/main/resources/templates/ 不在静态目录内,Thymeleaf 模板只能经控制器渲染,无法被 /** 直接下载源码。
  • 敏感文件不可达:application.properties、.class、RSA 私钥等都在四个静态目录之外,默认无法通过 URL 访问。
  • 路径穿越防护:资源处理器会拒绝 .. 之类的路径穿越,无法越出静态目录读取文件。
  • 控制器优先:业务路由不会被同名静态文件遮蔽,避免「改了个静态文件导致接口行为变化」这类隐蔽问题。
警示

常见的危险改动是把 spring.web.resources.static-locations 设成 classpath:/ 或 file:/ 根目录——这会把整个 classpath(含配置、私钥、class 文件)或磁盘暴露为静态资源,属于严重安全风险。除非明确知道后果,否则不要改动默认优先级。

相关配置项速查

以下属性都有安全、合理的默认值,日常开发通常 无需修改:

静态资源相关配置项及默认值
配置项默认值说明
spring.mvc.static-path-pattern/**静态资源的 URL 前缀
spring.web.resources.static-locations4 个 classpath 目录查找位置(按顺序)
spring.mvc.webjars-path-pattern/webjars/**WebJar 的 URL 前缀
spring.web.resources.add-mappingstrue是否启用默认资源映射

只有在确有必要(如自定义 CDN 路径、隔离静态目录)时才修改,并同步验证安全性。

总结归纳

一句话记住:Controller 优先,WebJar 次之,静态资源再次,欢迎页最后;静态文件优先放 static,同名时靠前目录胜出。

  • 写业务接口用 @Controller,永远优先于同名静态文件。
  • 普通静态资源放 src/main/resources/static/ 最省心。
  • 第三方前端库用 WebJar,走 /webjars/**。
  • 默认优先级即安全边界,除非明确需要,不要改 static-locations 或路径模式。

下一步:遇到 404 先对照目录表确认文件位置;遇到「接口被覆盖」的错觉,回顾控制器优先规则;若确需自定义,先记录默认行为,再做最小改动并验证安全性。

参考资料

  1. Spring Boot 官方文档 · Web 应用(Servlet)

    静态内容、欢迎页等默认行为的权威说明。

  2. Spring Framework · 静态资源

    ResourceHandler、路径解析与静态资源映射的实现细节。

  3. WebJars 官网

    WebJar 约定与可用库清单。

  4. Spring Framework · HandlerMapping

    处理器映射与优先级排序的说明。