最快集成方式是将静态HTML文件放入src/main/resources/static，但仅适用于纯前端页面；需动态渲染、数据注入或权限控制时，必须引入模板引擎（如Thymeleaf）或采用前后端分离架构。
直接放静态 HTML 文件到 src/main/resources/static 是最快集成方式，但仅适用于纯前端页面；一旦需要服务端动态渲染、数据注入或权限控制，就必须引入模板引擎或前后端分离架构。
静态资源目录直接托管 HTML
Spring Boot 默认将 src/main/resources/static 和 src/main/resources/public 视为静态资源根路径。把 index.html 放进去，访问 /index.html 就能立刻看到页面。
- 不支持 Thymeleaf 语法（如
th:text）、不能读取 Model 数据 - 所有 JS/CSS/图片需放在同级或子目录下，路径要按实际结构写（比如
./css/app.css） - 若 HTML 中有相对路径的 AJAX 请求，后端必须配置跨域或统一代理，否则 403/404
- 无法做登录态拦截——请求直接绕过 Spring Security 过滤器链
Thymeleaf 模板引擎渲染 HTML
这是 Spring Boot 官方推荐的服务器端渲染方案，适合需要后端拼数据、保持 SEO 友好、且不想拆前后端职责的项目。
- HTML 文件必须放在
src/main/resources/templates下，扩展名保持.html - 控制器返回字符串时，Spring Boot 自动匹配该路径下的 Thymeleaf 模板，例如
return "user/list"对应templates/user/list.html - 务必在
pom.xml中引入spring-boot-starter-thymeleaf，否则Model传参无效、th:*标签被原样输出 - Thymeleaf 默认开启 HTML 严格模式，自闭合标签如
<img src="" />必须写全，否则解析失败报错org.thymeleaf.exceptions.TemplateInputException
前后端分离：HTML 由前端框架生成并独立部署
当 HTML 页面含大量交互逻辑（如表格排序、表单联动、实时通知），硬塞进后端模板会增加维护成本；此时应让前端工程（Vue/React）构建出纯静态 HTML + JS bundle，后端只提供 REST API。
立即学习“前端免费学习笔记（深入）”；
- 前端构建产物（如
dist/）可整体复制到src/main/resources/static，但需注意：入口index.html中的 JS 路径（如/js/app.123.js）必须与实际部署路径一致 - 若前端路由用
history模式（无#），Spring Boot 需配置兜底路由，否则刷新子路径（如/user/123）会 404；可在@Controller中加一个@GetMapping("/**")返回"forward:/index.html" - API 基地址建议统一配在前端环境变量里（如
VUE_APP_API_BASE_URL），避免硬编码导致测试/生产环境切换出错
iframe 集成遗留 HTML 页面
老系统已有完整 HTML 页面，又不想重写，用 <iframe> 是最轻量的“胶水层”方案，但要注意通信与样式隔离问题。
- 父页面和 iframe 内容必须同源（协议+域名+端口一致），否则无法通过
window.postMessage通信或读取iframe.contentDocument - iframe 默认不自动撑高，内容变化后容易出现双滚动条；可用
iframe.onload+iframe.contentDocument.body.scrollHeight动态设高，但需确保 iframe 内页面已渲染完毕 - 若 iframe 页面含表单提交，其
target属性会影响整个父窗口跳转，建议显式设为_self或用 JS 拦截 submit 事件
真正卡住人的往往不是选哪种方式，而是没想清楚「这个 HTML 页面到底需不需要后端参与」：纯展示页扔 static 就行；带用户身份的数据页必须走模板或 API；而历史包袱重的老页面，iframe 不是权宜之计，反而是最可控的过渡手段。
