Spring Boot中Freemarker模板错误返回200，需改为500触发默认错误页

我之前也碰到过完全一样的困扰——Freemarker自带的异常处理逻辑怎么都没法让Spring抛出500错误，要么带着错误信息渲染出半页内容，要么悄悄停止渲染但响应状态码还是200。后来摸索出了一套靠谱的解决办法，核心思路是让Freemarker在模板出错时抛出一个能被Spring全局异常处理机制捕获的运行时异常，彻底绕过它自带的处理逻辑。

为什么默认配置达不到效果？ #

Freemarker的DEBUG和RETHROW模式本质上都是在模板渲染阶段内部消化异常：

• DEBUG模式会把错误信息直接输出到模板里，同时继续渲染之前的内容，响应状态始终是200；
• RETHROW模式虽然会停止渲染并隐藏错误信息，但它只是终止了模板输出，并没有让Spring的DispatcherServlet感知到这是一个需要返回500的未处理异常，所以响应状态依然保持200。

具体解决方案 #

1. 自定义Freemarker异常处理器

写一个实现TemplateExceptionHandler的类，让它在模板出错时直接抛出RuntimeException，把异常完全抛给Spring处理：

import freemarker.core.Environment;
import freemarker.template.TemplateException;
import freemarker.template.TemplateExceptionHandler;
import java.io.Writer;

public class RethrowForSpringErrorHandler implements TemplateExceptionHandler {
    @Override
    public void handleTemplateException(TemplateException te, Environment env, Writer out) throws TemplateException {
        // 将Freemarker异常包装为RuntimeException抛出，触发Spring的异常处理链
        throw new RuntimeException("模板渲染失败", te);
    }
}

2. 配置Spring使用自定义处理器

如果是Spring Boot项目，直接在application.yml或application.properties中配置：

spring:
  freemarker:
    settings:
      # 指定自定义异常处理器的全类名
      template_exception_handler: com.yourproject.handler.RethrowForSpringErrorHandler

如果是传统Spring MVC的XML配置：

<bean id="freeMarkerConfigurer" class="org.springframework.web.servlet.view.freemarker.FreeMarkerConfigurer">
    <property name="templateLoaderPath" value="/WEB-INF/templates/"/>
    <property name="freemarkerSettings">
        <props>
            <prop key="template_exception_handler">com.yourproject.handler.RethrowForSpringErrorHandler</prop>
        </props>
    </property>
</bean>

3. 确保Spring默认错误页生效

Spring Boot默认已经配置了/error端点处理500错误，会自动渲染默认的错误页面。如果需要自定义错误页，只需在src/main/resources/templates下创建error/500.ftl（对应Freemarker模板）即可。

注意事项 #

• 确保自定义处理器的包路径正确，Freemarker能正常加载到这个类；
• 如果项目中有自定义全局异常处理器，不要捕获这个RuntimeException，或者让它继续向上抛出，这样Spring的默认错误处理机制才能接管；
• 测试时可以故意在模板中写个错误（比如引用不存在的变量），验证是否会跳转到500错误页，同时响应状态码为500。

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