SpringBoot整合HTML页面教程

本文深入解析了Spring Boot中HTML页面整合的核心机制与常见陷阱，清晰区分了static目录（直接HTTP映射纯静态资源）与templates目录（需@Controller配合Thymeleaf等模板引擎渲染）的根本差异，直击开发者最常踩的“404”“白页”“CSS/JS加载失败”等痛点，并给出精准排错路径：从目录放置、控制器注解选择（@Controller而非@RestController）、Thymeleaf命名空间声明与变量传递，到静态资源路径书写规范（th:href="@{...}" vs 绝对路径）、Security放行配置及IDE编译设置，手把手厘清“静态直出”与“模板渲染”两条技术路线的本质区别——真正解决问题的关键，永远是看懂浏览器地址栏和Network面板中那个真实的请求URL。

Spring Boot 默认静态资源路径怎么配

Spring Boot 不会自动把 src/main/java 下的 HTML 当页面渲染，它只认特定目录里的静态文件。默认情况下，src/main/resources/static 和 src/main/resources/templates 是两个关键位置，但作用完全不同：static 里放纯 HTML/CSS/JS（不经过模板引擎），直接 HTTP 映射；templates 里放 Thymeleaf、Freemarker 等模板文件，需要控制器跳转才能渲染。

• 放错目录最常见：把 HTML 扔进 src/main/java 或 src/main/resources 根目录，结果 404
• 想用纯 HTML 不走模板？必须放 static，且访问路径就是文件名，比如 static/index.html → http://localhost:8080/index.html
• 如果用了 Thymeleaf，HTML 得放 templates，还得写一个 @Controller 返回视图名，不能直接访问 .html 路径
• application.properties 里改 spring.web.resources.static-locations 可以自定义路径，但别轻易动，默认够用

为什么访问 HTML 返回白页或 404

不是代码写错了，大概率是“没走对路”——Spring Boot 的静态资源处理和 MVC 拦截机制在背后打架。

• 如果加了 @EnableWebMvc，整个默认配置被清空，static 目录失效，必须手动配 WebMvcConfigurer 添加资源处理器
• 写了 @RestController 却想返回 HTML？不行。必须用 @Controller，否则返回的是字符串字面量，不是页面
• 路径带 .html 后缀但没配 spring.mvc.view.suffix=.html（Thymeleaf 场景下不需要设这个）——其实 Thymeleaf 默认不依赖后缀，靠前缀+后缀拼路径，设了反而容易错
• 用 IDE 运行时没编译资源？检查 Maven 是否勾选了 “Build project automatically”，或者手动 mvn clean compile

Thymeleaf 页面怎么让变量生效

放进 templates 目录只是第一步，HTML 里写 ${xxx} 不会自动替换，得靠控制器传值 + 正确的命名空间声明。

• HTML 文件第一行必须有 xmlns:th="http://www.thymeleaf.org"，否则 th:text 之类全被当普通属性忽略
• 控制器方法要返回 String（视图名），不是 ResponseEntity 或 @ResponseBody，例如 return "user"; 对应 templates/user.html
• 传参用 Model 或 ModelMap，不是 HttpServletRequest.setAttribute() —— Spring Boot 里后者无效
• Thymeleaf 默认禁用表达式缓存（开发模式），但如果你在 application.properties 里加了 spring.thymeleaf.cache=true，改完 HTML 不重启就看不到效果

内嵌 CSS/JS 加载失败怎么办

静态资源路径写错是主因。Thymeleaf 页面里不能写 href="css/app.css" 这种相对路径，浏览器会按当前 URL 拼，而不是按项目根目录。

• Thymeleaf 推荐用 th:href="@{/css/app.css}"，它会自动补上下文路径（比如 /myapp/css/app.css）
• 纯静态 HTML 放 static 目录下，引用要用绝对路径 /css/app.css，开头斜杠不能少
• 如果用了 Spring Security，记得放开静态资源路径，比如 web.ignoring().requestMatchers("/css/**", "/js/**", "/images/**")
• Chrome 控制台报 404 时，点开链接看实际请求地址——常会发现多了一层 context path 或少了一层 static，根源还是路径生成逻辑没理清

最麻烦的不是配置，是分不清“静态资源直出”和“模板渲染”这两条路。同一个 HTML 文件，放错目录、用错控制器、写错引用方式，表现可能一模一样：空白页。盯住浏览器地址栏和 Network 面板里的真实请求路径，比翻文档更快定位问题。

到这里，我们也就讲完了《SpringBoot整合HTML页面教程》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！