麻雀窝 Sparrow Zoo

Thymeleaf 配置踩坑:prefix 不能带尾斜杠

记录 Thymeleaf 视图解析「找不到资源」报错的根因:Controller 视图名带前导斜杠时,spring.thymeleaf.prefix 一旦多出尾斜杠就会拼出双斜杠路径;给出正确配置与踩坑清单。

使用 Spring Boot + Thymeleaf 的后端开发者(Thymeleaf 3.1 / Spring Boot 2.x、3.x)发布于 更新于
prefix 尾斜杠视图名带前导斜杠时正确prefix=classpath:templates→ templates/upload.html错误prefix=classpath:templates/→ templates//upload.html二者只需一处分隔斜杠
阅读目录

结论先行

结论:当 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 下查找文件:

code
实际模板路径 = 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 写成带尾斜杠的形式:

code
# 错误写法:末尾多了一个 /\nspring.thymeleaf.prefix=classpath:templates/

访问 /upload 或 /spring-upload 时,会直接报错,提示找不到模板资源。

现象

视图解析失败,日志/响应里出现类似「resource not found」「找不到资源」的错误,模板明明就躺在 templates 目录下却加载不出来。

根因:双斜杠路径

回到拼接规则 prefix + 视图名 + suffix,关键在于视图名本身带了前导斜杠。于是两种写法拼出来的结果完全不同:

code
# 正确: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 永远不能加尾斜杠。二者只需一处提供分隔斜杠。

正确配置

code
spring.thymeleaf.cache=false\nspring.thymeleaf.favicon.enabled=false\nspring.thymeleaf.prefix=classpath:templates\nspring.thymeleaf.suffix=.html
关键配置项
项值说明
prefixclasspath:templates无尾斜杠,配合视图名前导斜杠使用
suffix.html模板文件扩展名

正确的解析示例:

正确解析结果
视图名拼出的路径对应文件
/uploadclasspath:templates/upload.htmltemplates/upload.html
/spring-uploadclasspath:templates/spring-upload.htmltemplates/spring-upload.html

注意事项与踩坑清单

Thymeleaf prefix 踩坑清单
坑现象正确做法
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 验证模板能正常渲染;再把这条约定写进团队规范,避免重复踩坑。

参考资料

  1. Thymeleaf 官方教程 · Using Thymeleaf

    模板引擎的基本用法与视图解析概念,适用于 Thymeleaf 3.1。

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

    Spring Boot 中 Thymeleaf 自动配置与视图解析器的默认行为说明。

  3. Spring Boot · 应用配置属性附录

    spring.thymeleaf.prefix / suffix 等属性的默认值与含义。