必须使用spring boot 4.0.0版starter依赖并显式配置template-loader-path、charset等参数，否则因模块重构和路径/编码失效导致模板找不到或乱码。
要在Spring Boot 4.0版本中正确启用FreeMarker模板引擎并完成视图层渲染，必须适配新版本对Starter依赖、自动配置机制及模板加载策略的调整——旧版2.x/3.x的配置方式在4.0中已失效，直接沿用会导致TemplateNotFoundException或空白响应。
添加兼容4.0的FreeMarker Starter依赖
打开pom.xml，删除任何spring-boot-starter-freemarker 3.x及以下版本声明，替换为Spring Boot 4.0官方认证的坐标：
这一步不可跳过：Spring Boot 4.0将FreeMarker Starter重构为模块化组件，【未显式指定4.0.0版本将触发Maven降级解析，拉取3.3.x兼容包，导致template-loader-path失效】。
配置application.yml（关键路径与编码强制生效）
在src/main/resources/application.yml中写入以下配置：
spring:
freemarker:
template-loader-path: classpath:/templates/
suffix: .ftl
content-type: text/html
charset: UTF-8
cache: false
expose-request-attributes: true
expose-session-attributes: true
注意：【4.0版本废弃了template-loader-path的复数形式template-loader-paths，使用后者会静默忽略路径配置】。同时，charset必须显式声明，否则中文变量输出为乱码且无报错提示。
创建标准模板目录结构
在src/main/resources下新建文件夹：templates。
进入该文件夹，新建一个名为index.ftl的文件，内容为：
欢迎 ${name}！
必须确保文件保存为UTF-8无BOM格式——IDEA默认可能带BOM，导致FreeMarker解析失败并抛出Unexpected character异常。
编写Controller返回视图名称
方法一：使用Model + String返回值（推荐）
@Controller
public class ViewController {
@GetMapping("/home")
public String home(Model model) {
model.addAttribute("name", "张工");
return "index";
}
}
方法二：使用ModelAndView（需显式设置viewName）
@Controller
public class ViewController {
@GetMapping("/home")
public ModelAndView home() {
ModelAndView mv = new ModelAndView();
mv.addObject("name", "张工");
mv.setViewName("index");
return mv;
}
}
两种方式均可，但方法一更轻量；【return值必须是纯模板名（不带路径、不带后缀），如"index"而非"templates/index.ftl"或"/index"】。
启动验证与常见错误拦截
第一步：运行Spring Boot应用，访问http://localhost:8080/home。
第二步：若页面显示“欢迎 张工！”，说明渲染成功。
第三步：若返回404或白页，立即检查：
① 控制台是否打印WARN freemarker.cache.TemplateCache - Template not found for name "index"；
② 检查templates文件夹是否位于src/main/resources下（不是src/main/java）；
③ 执行mvn clean compile，确认target/classes/templates/目录下存在index.ftl。
第四步：若中文显示为方块或问号，回到application.yml确认charset: UTF-8已写入且缩进正确（YAML对空格敏感）。
