结论先行
结论:当 Controller 返回的视图名自带前导斜杠(如 /upload)时,spring.thymeleaf.prefix 就不能带尾斜杠。正确写法是 classpath:templates(而非 classpath:templates/),二者只需一处提供分隔斜杠。
原理是 Thymeleaf 视图解析按 实际路径 = prefix + 视图名 + suffix 拼接:无尾斜杠的 prefix 与带前导斜杠的视图名拼出 classpath:templates/upload.html,正确命中;一旦 prefix 多出尾斜杠,就会和视图名的前导斜杠叠加成 classpath:templates//upload.html 的双斜杠路径,资源定位失败,报「找不到资源」。
这条约定在本项目中是统一的:视图名一律带前导 /,因此 prefix 永远不加尾 /。
问题背景
Thymeleaf 是 Spring Boot 生态里常用的服务端模板引擎。Controller 返回一个视图名(ModelAndView)后,Thymeleaf 的视图解析器会按一条固定规则拼出模板的实际路径,再去 classpath 下查找文件:
实际模板路径 = prefix + 视图名 + suffix本项目在 application.properties 里配置了 prefix 与 suffix:
spring.thymeleaf.cache=false\nspring.thymeleaf.favicon.enabled=false\nspring.thymeleaf.prefix=classpath:templates\nspring.thymeleaf.suffix=.html同时,Controller 返回的视图名自带前导斜杠:
@RestController\npublic class Controller {\n @RequestMapping(\"upload\")\n public ModelAndView upload() {\n return new ModelAndView(\"/upload\"); // 注意前导斜杠\n }\n\n @RequestMapping(\"spring-upload\")\n public ModelAndView springUpload() {\n return new ModelAndView(\"/spring-upload\");\n }\n}模板文件位于 src/main/resources/templates/ 下:upload.html 和 spring-upload.html。
详细内容
问题:找不到资源
如果把 prefix 写成带尾斜杠的形式:
# 错误写法:末尾多了一个 /\nspring.thymeleaf.prefix=classpath:templates/访问 /upload 或 /spring-upload 时,会直接报错,提示找不到模板资源。
视图解析失败,日志/响应里出现类似「resource not found」「找不到资源」的错误,模板明明就躺在 templates 目录下却加载不出来。
根因:双斜杠路径
回到拼接规则 prefix + 视图名 + suffix,关键在于视图名本身带了前导斜杠。于是两种写法拼出来的结果完全不同:
# 正确:prefix 无尾斜杠,靠视图名的前导 / 补全分隔\nclasspath:templates + /upload + .html = classpath:templates/upload.html ✓ 命中模板\n\n# 错误:prefix 有尾斜杠,和视图名的前导 / 叠加成双斜杠\nclasspath:templates/ + /upload + .html = classpath:templates//upload.html ✗ 路径不存在classpath:templates//upload.html 里出现了两个连续斜杠,classpath 资源定位时按这个「不存在的路径」去找文件,自然找不到,于是报「找不到资源」。
本项目视图名统一带前导斜杠(/upload、/spring-upload),因此 spring.thymeleaf.prefix 永远不能加尾斜杠。二者只需一处提供分隔斜杠。
正确配置
spring.thymeleaf.cache=false\nspring.thymeleaf.favicon.enabled=false\nspring.thymeleaf.prefix=classpath:templates\nspring.thymeleaf.suffix=.html| 项 | 值 | 说明 |
|---|---|---|
prefix | classpath:templates | 无尾斜杠,配合视图名前导斜杠使用 |
suffix | .html | 模板文件扩展名 |
正确的解析示例:
| 视图名 | 拼出的路径 | 对应文件 |
|---|---|---|
/upload | classpath:templates/upload.html | templates/upload.html |
/spring-upload | classpath:templates/spring-upload.html | templates/spring-upload.html |
注意事项与踩坑清单
| 坑 | 现象 | 正确做法 |
|---|---|---|
prefix 带尾斜杠 classpath:templates/ | 拼出 classpath:templates//xxx.html,报「找不到资源」 | prefix 去掉尾斜杠,写成 classpath:templates |
| 视图名与 prefix 同时带斜杠 | 同上,双斜杠路径 | 约定「视图名带前导 / + prefix 无尾 /」,只需一处补全分隔 |
| 视图名漏写前导斜杠 | 拼出 classpath:templatesupload.html,同样找不到 | 保持视图名带前导斜杠(/upload) |
视图名带前导 /,prefix 就不带尾 /;反过来 prefix 带尾 /,视图名就别带前导 /。本项目的约定是前者。
总结归纳
一句话记住:视图名带前导 /,prefix 就不能带尾 /——二者只需一处补全分隔斜杠。本项目统一让视图名带前导斜杠,因此 spring.thymeleaf.prefix 永远写成不带尾斜杠的 classpath:templates。
- 拼接规则:
实际路径 = prefix + 视图名 + suffix,出现双斜杠会直接导致资源定位失败。 - 正确配置:
spring.thymeleaf.prefix=classpath:templates、spring.thymeleaf.suffix=.html。 - 报错先查:prefix 是否多了尾斜杠、视图名是否漏了前导斜杠。
下一步:把配置里的尾斜杠去掉,用 /upload、/spring-upload 验证模板能正常渲染;再把这条约定写进团队规范,避免重复踩坑。
参考资料
- Thymeleaf 官方教程 · Using Thymeleaf
模板引擎的基本用法与视图解析概念,适用于 Thymeleaf 3.1。
- Spring Boot 官方文档 · Web 应用(Servlet)
Spring Boot 中 Thymeleaf 自动配置与视图解析器的默认行为说明。
- Spring Boot · 应用配置属性附录
spring.thymeleaf.prefix / suffix 等属性的默认值与含义。