在 Spring Boot 项目开发中，静态页面（如 HTML）是展示前端内容的重要载体。无论是简单的官网展示，还是复杂系统的前端界面，都需要通过合理的配置让 Spring Boot 正确识别和加载静态资源。本文将从项目初始化开始，详细讲解 Spring Boot 静态页面的配置方法，涵盖主流模板引擎（Thymeleaf、FreeMarker）的集成、静态资源映射规则、页面跳转实现及常见问题排查，帮助开发者快速掌握静态页面配置技巧。
一、项目初始化与基础配置
在配置静态页面之前，首先需要搭建一个标准的 Spring Boot 项目。推荐使用 Spring Initializr（https://start.spring.io/）快速生成项目骨架，步骤如下：
1.1 项目创建参数
Project Type：Maven（或 Gradle，本文以 Maven 为例）
Language：Java
Spring Boot Version：选择稳定版本（如 2.7.x 或 3.2.x，避免使用快照版）
Group/Artifact：自定义项目坐标（如 com.example/demo）
Dependencies：初始仅需添加「Spring Web」依赖（后续根据模板引擎需求补充）
生成项目后，解压并导入 IDE（如 IntelliJ IDEA），等待 Maven 依赖下载完成。
1.2 默认项目结构
Spring Boot 对静态资源和页面文件有默认的目录约定，无需额外配置即可生效，标准结构如下：
src/
├── main/
│ ├── java/ # Java代码目录（含Controller等）
│ └── resources/ # 资源目录
│ ├── static/ # 静态资源目录（CSS、JS、图片等）
│ ├── templates/ # 模板页面目录（HTML模板文件）
│ └── application.properties # 全局配置文件
└── pom.xml # Maven依赖配置
static 目录：用于存放无需模板引擎解析的静态资源，如纯 HTML、CSS、JavaScript、图片等。Spring Boot 默认映射/路径到该目录，例如static/index.html可通过http://localhost:8080/index.html访问。
templates 目录：用于存放需要模板引擎解析的动态 HTML 页面（如 Thymeleaf、FreeMarker 模板）。该目录下的文件无法直接通过 URL 访问，必须通过 Controller 跳转加载。
二、主流模板引擎配置实战
Spring Boot 支持多种模板引擎，其中Thymeleaf（官方推荐）和FreeMarker最为常用。以下分别讲解两种引擎的集成与配置步骤。
2.1 Thymeleaf 配置（官方推荐）
Thymeleaf 是一款面向 Java 的 XML/XHTML/HTML5 模板引擎，支持在 HTML 中嵌入表达式，实现动态内容渲染，且无需编译，开发效率高。
步骤 1：添加 Thymeleaf 依赖
在pom.xml中引入 Thymeleaf starter 依赖，Spring Boot 会自动配置相关 Bean（如TemplateEngine）：
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>
步骤 2：配置 Thymeleaf（可选）
Thymeleaf 的默认配置已满足大部分场景，若需自定义（如模板编码、缓存开关），可在application.properties中添加以下配置：
# 模板文件编码（默认UTF-8）
spring.thymeleaf.encoding=UTF-8
# 模板文件后缀（默认.html）
spring.thymeleaf.suffix=.html
# 模板文件前缀（默认classpath:/templates/）
spring.thymeleaf.prefix=classpath:/templates/
# 开发环境关闭模板缓存（避免修改后需重启项目）
spring.thymeleaf.cache=false
# 模板模式（默认HTML5，支持HTML、XML等）
spring.thymeleaf.mode=HTML5
关键注意点：开发环境务必关闭cache（设为false），否则修改 HTML 后需重启项目才能生效；生产环境建议开启（true），提升性能。
步骤 3：创建 Thymeleaf 模板页面
在resources/templates目录下创建index.html，使用 Thymeleaf 表达式（th:text）渲染动态数据：
<!DOCTYPE html>
<!-- 引入Thymeleaf命名空间，支持表达式语法 -->
<html xmlns:th="http://www.thymeleaf.org">
<head>
<meta charset="UTF-8">
<title>Thymeleaf静态页面</title>
<!-- 引入static目录下的CSS（通过/路径映射） -->
<link rel="stylesheet" th:href="@{/css/style.css}">
</head>
<body>
<!-- 动态渲染Controller传递的message参数 -->
<h1 th:text="${message}">默认文本（未渲染时显示）</h1>
<!-- 引入static目录下的JS -->
<script th:src="@{/js/main.js}"></script>
</body>
</html>
注意使用th:href和th:src引用静态资源，而非原生href/src，确保路径在不同环境下正确映射。
步骤 4：创建 Controller 跳转页面
在java/com/example/demo/controller目录下创建PageController，通过@Controller注解定义页面跳转接口：
package com.example.demo.controller;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
@Controller
public class PageController {
// 访问http://localhost:8080/ 跳转到index.html
@GetMapping("tv.pearLtabLeware.com")
public String index(tsl.pearLtabLeware.com) {
// 向页面传递参数（key为message，value为动态内容）
model.addAttribute("zb.pearLtabLeware.com", "Hello Thymeleaf! 这是Spring Boot静态页面");
// 返回模板页面名称（无需加.html后缀，默认匹配templates/index.html）
return "index";
}
}
启动项目后，访问http://localhost:8080，即可看到动态渲染后的页面，且 CSS/JS 资源能正常加载。
2.2 FreeMarker 配置
FreeMarker 是一款老牌模板引擎，语法简洁，支持复杂的逻辑判断和循环，适合需要高度定制化的动态页面场景。
步骤 1：添加 FreeMarker 依赖
在pom.xml中引入 FreeMarker starter 依赖：
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-freemarker</artifactId>
</dependency>
步骤 2：配置 FreeMarker（可选）
FreeMarker 的默认配置可通过application.properties修改，常用配置如下：
# 模板文件后缀（默认.ftl，也可改为.html）
spring.freemarker.suffix=.html
# 模板文件前缀（默认classpath:/templates/）
spring.freemarker.prefix=classpath:/templates/
# 模板编码（默认UTF-8）
spring.freemarker.charset=UTF-8
# 开发环境关闭缓存
spring.freemarker.cache=false
# 模板类型（默认text/html）
spring.freemarker.content-type=text/html
若希望使用.html作为模板后缀（而非默认的.ftl），需显式配置spring.freemarker.suffix=.html，避免与纯静态 HTML 混淆。
步骤 3：创建 FreeMarker 模板页面
在resources/templates目录下创建freemarker-index.html，使用 FreeMarker 表达式（${}）渲染数据：
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>FreeMarker静态页面</title>
<link rel="stylesheet" href="/css/style.css"> <!-- 直接使用/映射static目录 -->
</head>
<body>
<!-- FreeMarker表达式渲染参数 -->
<h1>${message}</h1>
<!-- FreeMarker循环示例（若Controller传递list参数） -->
<ul>
<#list userList as user>
<li>${user.name} - ${user.age}</li>
</#list>
</ul>
<script src="/js/main.js"></script>
</body>
</html>
步骤 4：创建 Controller 跳转
在PageController中添加 FreeMarker 页面的跳转接口：
@GetMapping("/freemarker")
public String freemarkerPage(Model model) {
model.addAttribute("message", "Hello FreeMarker!");
// 模拟传递列表数据
List<User> userList = Arrays.asList(
new User("张三", 20),
new User("李四", 22)
);
model.addAttribute("userList", userList);
// 返回模板页面名称（匹配templates/freemarker-index.html）
return "freemarker-index";
}
启动项目后，访问http://localhost:8080/freemarker，即可看到循环渲染的用户列表。
三、静态资源（CSS/JS/ 图片）配置
Spring Boot 默认对静态资源有自动映射规则，但在实际开发中，可能需要自定义资源路径或处理多模块项目的资源共享，以下讲解常见配置场景。
3.1 默认静态资源映射规则
Spring Boot 默认将以下 4 个目录作为静态资源目录（优先级从高到低）：
classpath:/META-INF/resources/（第三方 jar 包中的静态资源）
classpath:/resources/（自定义资源目录，需手动创建）
classpath:/static/（默认静态资源目录，推荐使用）
classpath:/public/（公开资源目录，可用于存放无需权限的静态文件）
所有目录下的资源均可通过http://localhost:8080/资源路径直接访问，例如：
static/css/style.css →http://localhost:8080/css/style.css
public/images/logo.png →http://localhost:8080/images/logo.png
3.2 自定义静态资源路径
若需修改默认资源目录（如将静态资源放在classpath:/webapp/下），可通过以下两种方式配置：
方式 1：配置文件指定（推荐）
在application.properties中添加以下配置，指定自定义静态资源目录：
# 自定义静态资源目录（多个目录用逗号分隔）
spring.resources.static-locations=classpath:/webapp/,classpath:/static/
# 静态资源访问前缀（可选，如配置后需通过http://localhost:8080/static/css/style.css访问）
spring.mvc.static-path-pattern=/static/**
spring.resources.static-locations：覆盖默认目录，若需保留默认目录，需手动添加（如上述配置保留了static/）。
spring.mvc.static-path-pattern：添加访问前缀，避免静态资源路径与 API 接口冲突（如 API 接口为/api/**，静态资源为/static/**）。
方式 2：Java 配置类（灵活）
通过实现WebMvcConfigurer接口，重写addResourceHandlers方法，自定义资源映射：
package com.example.demo.config;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
// 配置外部磁盘资源（如D盘static目录，适合大文件存储）
registry.addResourceHandler("/external/**") // 访问路径前缀
.addResourceLocations("file:D:/static/"); // 本地磁盘路径（需加file:前缀）
// 配置类路径资源（补充默认目录）
registry.addResourceHandler("/**")
.addResourceLocations("classpath:/webapp/")
.addResourceLocations("classpath:/static/");
}
}
场景适用：若静态资源存放在服务器磁盘（而非项目内），需使用file:前缀指定绝对路径，避免项目打包时包含过大的静态文件。
四、页面跳转与路径问题排查
在静态页面配置中，最常见的问题是 “页面 404” 或 “静态资源加载失败”，以下总结核心排查点和解决方案。
4.1 页面 404 问题排查
Controller 注解是否正确：
页面跳转必须使用@Controller注解，而非@RestController（@RestController会将返回值作为 JSON，而非模板页面名称）。
确保@GetMapping的路径与访问 URL 一致（如@GetMapping("/index")对应http://localhost:8080/index）。
模板页面路径是否匹配：
若使用 Thymeleaf/FreeMarker，页面需放在templates目录下，且 Controller 返回的页面名称需与文件名一致（无需后缀，除非自定义了suffix）。
检查spring.thymeleaf.prefix或spring.freemarker.prefix配置是否正确（默认classpath:/templates/，若修改需确保路径存在）。
依赖是否缺失：
若使用模板引擎，需确认对应的 starter 依赖已添加（如 Thymeleaf 需spring-boot-starter-thymeleaf），否则 Spring Boot 无法解析模板页面。
4.2 静态资源加载失败（404）排查
资源路径是否正确：
模板页面中引用静态资源时，若使用模板引擎语法（如 Thymeleaf 的th:href），需用@{/资源路径}（如@{/css/style.css}），而非相对路径（如../css/style.css，易因页面路径层级变化导致错误）。
纯静态 HTML（放在static目录下）可直接使用/资源路径（如/js/main.js），无需模板语法。
自定义资源路径配置是否正确：
若配置了spring.mvc.static-path-pattern，访问资源时需添加前缀（如配置/static/**，则资源路径为/static/css/style.css）。
若使用外部磁盘资源，检查file:路径是否正确（如D:/static/需存在，且文件权限可读取）。
拦截器是否拦截静态资源：
若项目中自定义了拦截器（如登录拦截），需确保拦截器不拦截静态资源路径。可在WebMvcConfig中配置排除路径：
@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(new LoginInterceptor())
.addPathPatterns("/**") // 拦截所有请求
.excludePathPatterns("/static/**", "/login", "/index.html"); // 排除静态资源和登录页
}
五、总结与最佳实践
开发环境与生产环境区分：
开发环境：关闭模板缓存（spring.thymeleaf.cache=false），方便实时预览页面修改。
生产环境：开启模板缓存，将静态资源（CSS/JS/ 图片）压缩后部署到 CDN，提升访问速度。
模板引擎选择：
若需简单的动态渲染（如数据展示），优先选择 Thymeleaf（官方推荐，学习成本低）。
若需复杂逻辑（如循环嵌套、条件判断），可选择 FreeMarker（语法灵活，功能强大）。
若为纯静态页面（无动态数据），直接将 HTML 放在static目录下，无需引入模板引擎。
资源路径规范：
静态资源按类型分类存放（如static/css/、static/js/、static/images/），便于维护。
避免使用相对路径引用资源，统一使用/开头的绝对路径（或模板引擎的@{}语法），确保路径一致性。
通过本文的配置步骤和问题排查方法，相信开发者能快速解决 Spring Boot 静态页面配置中的常见问题，高效完成前端页面与后端的整合。
