Spring Boot 3.0+需用Freemarker 2.4.0+以兼容Jakarta EE，配置需指定模板路径、编码和共享变量，Java对象访问须遵循BeanWrapper规则，路径问题优先检查classpath加载策略。
Freemarker 依赖怎么加才不会冲突
Java 项目里加 Freemarker，最常踩的坑是版本和 Servlet 容器不匹配。比如 Spring Boot 3.x 默认用 Jakarta EE 9+，而 freemarker 2.3.x 系列只认 javax.servlet，一启动就报 NoClassDefFoundError: javax/servlet/ServletException。
实操建议：
立即学习“Java免费学习笔记（深入）”；
- Spring Boot 2.7 及以下 → 用
freemarker2.3.31（或 2.3.32） - Spring Boot 3.0+ → 必须升到
freemarker2.4.0+，它已切到jakarta.servlet - Maven 里别同时引
freemarker和spring-boot-starter-freemarker，后者已含前者，重复会触发类加载冲突 - 非 Spring 项目，直接加
freemarker依赖即可，但要手动配Configuration实例，别漏掉setClassLoaderForTemplateLoading
freemarker.template.Configuration 初始化要点
Configuration 是 Freemarker 渲染的入口，但很多人在多线程场景下复用单例时出错——不是线程不安全，而是模板缓存、默认编码、空值处理策略这些属性一旦设错，会影响所有后续渲染。
实操建议：
立即学习“Java免费学习笔记（深入）”；
- 必须调用
setDirectoryForTemplateLoading或setClassForTemplateLoading指定路径，否则getTemplate一定抛IOException - 显式设
setDefaultEncoding("UTF-8")，否则 Windows 下读 .ftl 文件容易乱码 - 用
setSharedVariable注入常用工具类（如dateUtils），比每次template.process(data, out)传更稳 - 开发期可开
setTemplateUpdateDelay(0)热加载，但上线必须关，否则性能暴跌
ftl 文件里访问 Java 对象的常见陷阱
FreeMarker 不是反射黑盒，它靠 BeanWrapper 机制访问字段/方法，很多看似合理的写法会静默失败或报 TemplateProcessingException。
实操建议：
立即学习“Java免费学习笔记（深入）”；
- Java 类字段没 getter？
${user.name}直接报错，必须有getName()方法 - Map 类型推荐用
map?keys而不是map.keySet()，后者在 Freemarker 里不是合法表达式 - 判空别写
user != null && user.name?has_content，直接user.name?has_content就行，FreeMarker 自动短路 - 日期格式化统一走
?string("yyyy-MM-dd")，别在 Java 层转成 String 再传，否则失去时区控制能力
渲染时报 TemplateNotFoundException 怎么快速定位
这个错误表面是文件没找到，但真实原因常藏在路径解析逻辑里：类路径 vs 文件系统路径、斜杠方向、是否带扩展名、是否被 IDE 编译忽略。
实操建议：
立即学习“Java免费学习笔记（深入）”；
- 检查
Configuration的模板加载路径是否包含src/main/resources（Maven 默认资源目录），IDE 运行时可能没把 ftl 复制进target/classes - 用绝对路径调试：
configuration.getTemplate("/templates/user.ftl")，注意开头的/表示从 classpath 根开始 - 打印
configuration.getTemplateLookupStrategy()看当前策略，避免误以为支持通配符而实际只查固定后缀 - 如果用 Spring Boot，确认
spring.freemarker.template-loader-path配置值末尾没多加/，否则路径拼接会变成classpath:/templates//user.ftl
FreeMarker 的麻烦不在语法，而在环境链路上每一步都得对齐：依赖版本、类加载路径、编码设定、对象访问规则，缺一不可。最容易被忽略的是模板加载路径在不同运行环境（IDE / Maven exec / 打 jar 包）下的行为差异，建议上线前用 configuration.listTemplates() 主动枚举一次，看实际能扫到哪些文件。
