结论先行
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 的映射决定由谁处理。默认优先级从高到低为:
- 控制器映射(
RequestMappingHandlerMapping)——处理@Controller/@RequestMapping定义的路由。 - 资源处理器(
SimpleUrlHandlerMapping)——处理静态资源与 WebJar。 - 欢迎页(
WelcomePageHandlerMapping)——只处理根路径/,返回index.html。
关键结论:控制器永远优先于静态资源。若同时存在 @GetMapping("/about") 与静态文件 static/about.html,访问 /about 命中控制器;反之,静态文件也无法「抢走」已有控制器的路由。
| 优先级 | 处理器 | 典型对象 |
|---|---|---|
| 1(最高) | RequestMappingHandlerMapping | @Controller 方法 |
| 2 | SimpleUrlHandlerMapping | WebJar /webjars/** |
| 3 | SimpleUrlHandlerMapping | 静态资源 /** |
| 4(最低) | WelcomePageHandlerMapping | index.html(仅 /) |
静态资源的四个默认目录
Spring Boot 默认从以下 classpath 位置按顺序查找静态资源(spring.web.resources.static-locations 的默认值):
classpath:/META-INF/resources/(优先级最高)classpath:/resources/classpath:/static/classpath:/public/(优先级最低)
以 Maven 项目为例,这些目录对应 src/main/resources/ 下的同名子目录。请求 /css/app.css 时,Spring 会依次在这些目录下找 css/app.css,第一个命中的生效;同名文件放在多个目录时,靠前的目录胜出。
| 顺序 | classpath 位置 | Maven 对应目录 |
|---|---|---|
| 1 | classpath:/META-INF/resources/ | src/main/resources/META-INF/resources/ |
| 2 | classpath:/resources/ | src/main/resources/resources/ |
| 3 | classpath:/static/ | src/main/resources/static/ |
| 4 | classpath:/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 后,可访问:
/webjars/jquery/3.6.0/jquery.min.jsWebJar 与普通静态资源路径不重叠(/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) | 最高 |
| WebJar | classpath:/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-locations | 4 个 classpath 目录 | 查找位置(按顺序) |
| spring.mvc.webjars-path-pattern | /webjars/** | WebJar 的 URL 前缀 |
| spring.web.resources.add-mappings | true | 是否启用默认资源映射 |
只有在确有必要(如自定义 CDN 路径、隔离静态目录)时才修改,并同步验证安全性。
总结归纳
一句话记住:Controller 优先,WebJar 次之,静态资源再次,欢迎页最后;静态文件优先放 static,同名时靠前目录胜出。
- 写业务接口用
@Controller,永远优先于同名静态文件。 - 普通静态资源放
src/main/resources/static/最省心。 - 第三方前端库用 WebJar,走
/webjars/**。 - 默认优先级即安全边界,除非明确需要,不要改
static-locations或路径模式。
下一步:遇到 404 先对照目录表确认文件位置;遇到「接口被覆盖」的错觉,回顾控制器优先规则;若确需自定义,先记录默认行为,再做最小改动并验证安全性。
参考资料
- Spring Boot 官方文档 · Web 应用(Servlet)
静态内容、欢迎页等默认行为的权威说明。
- Spring Framework · 静态资源
ResourceHandler、路径解析与静态资源映射的实现细节。
- WebJars 官网
WebJar 约定与可用库清单。
- Spring Framework · HandlerMapping
处理器映射与优先级排序的说明。