如何解决Spring Boot集成FreeMarker的TemplateNotFoundException并指定自定义模板路径

报错核心原因 #

该报错本质是FreeMarker未显式配置合法的template_loader，默认使用的LegacyDefaultFileTemplateLoader未指定基础目录，无法定位到目标模板，同时默认加载器还存在安全风险，必须手动调整配置。

通用修复逻辑 #

• 为FreeMarker的Configuration实例显式调用setTemplateLoader方法设置合法的模板加载器，禁止使用默认加载器
• 可根据业务场景选择对应加载器：类路径下的模板用ClassTemplateLoader、本地文件系统的模板用FileTemplateLoader、Web应用场景用WebappTemplateLoader，需要多路径查找时可使用MultiTemplateLoader组合多个加载器

Spring Boot 集成场景自定义模板加载路径方案 #

方式1：配置文件直接指定（优先推荐，无需编写代码） #

在application.yml中添加如下配置即可自定义模板加载路径，多个路径用逗号分隔：

spring:
  freemarker:
    # 自定义模板加载路径，示例为类路径下的custom-templates目录和本地/opt/templates目录
    template-loader-path: classpath:/custom-templates/,file:/opt/templates
    suffix: .ftl
    charset: UTF-8

如果使用application.properties，对应配置如下：

spring.freemarker.template-loader-path=classpath:/custom-templates/,file:/opt/templates
spring.freemarker.suffix=.ftl
spring.freemarker.charset=UTF-8

方式2：代码自定义配置（适合复杂加载规则场景） #

如果需要灵活定制模板加载逻辑，可手动注册FreeMarkerConfigurer实例实现自定义配置：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.view.freemarker.FreeMarkerConfigurer;
import freemarker.cache.ClassTemplateLoader;
import freemarker.cache.FileTemplateLoader;
import freemarker.cache.MultiTemplateLoader;
import freemarker.cache.TemplateLoader;
import java.io.File;
import java.io.IOException;

@Configuration
public class FreeMarkerCustomConfig {
    @Bean
    public FreeMarkerConfigurer freeMarkerConfigurer() throws IOException {
        FreeMarkerConfigurer configurer = new FreeMarkerConfigurer();
        // 配置多个模板加载器，按顺序查找模板
        TemplateLoader classPathLoader = new ClassTemplateLoader(Thread.currentThread().getContextClassLoader(), "business-templates");
        TemplateLoader fileSystemLoader = new FileTemplateLoader(new File("/data/app/templates"));
        MultiTemplateLoader multiLoader = new MultiTemplateLoader(new TemplateLoader[]{classPathLoader, fileSystemLoader});
        
        configurer.setPostTemplateLoaders(multiLoader);
        configurer.setDefaultEncoding("UTF-8");
        return configurer;
    }
}

验证注意事项 #

• 配置的所有模板路径必须真实存在，应用运行进程需拥有路径的读取权限
• 调用getTemplate方法时传入的模板名称，需要和模板文件在加载路径下的相对路径完全匹配，注意大小写敏感问题

内容的提问来源于stack exchange，提问作者Roberto Bellarosa