bigywater.tech
Spring · 178

Whitelabel Error Page:Boot 4 里 server.error.* 不生效了,要改成 spring.web.error.*

Boot 4 里 server.error.include-message 为什么不生效?Whitelabel Error Page 怎么关?静态 404 页和自定义 ErrorController 各有什么限制?这篇在 Spring Boot 4.0.8 上逐项请求。

旧 key 不生效
server.error.include-message、include-stacktrace、whitelabel.enabled 在 4.0.8 里写了不报错,JSON 与页面一点不变
spring.web.error.*
新 key 打开后 /boom 的 JSON 多出 exception 与 message;include-stacktrace 多出超过 1000 个字符的 trace
406
自己写的 ErrorController 只返回 JSON 时,浏览器(Accept: text/html)访问不存在的路径得到 406、空响应体

默认

实测 · 本机执行输出
  浏览器访问 /nope(Accept: text/html):404 text/html | <html><body><h1>Whitelabel Error Page</h1><p>This application has no explicit mapping for /error, so you are seeing this as a fallback.</p><div id='created'>…</div><div>There was an unexpected error (type=Not Found, status=404).</div></body></html>
  接口访问 /nope(Accept: application/json):404 application/json | {"timestamp":"…","status":404,"error":"Not Found","path":"/nope"}
  curl 默认的 Accept(*/*)访问 /nope:404 application/json | {"timestamp":"…","status":404,"error":"Not Found","path":"/nope"}
  接口访问 /boom:500 application/json | {"timestamp":"…","status":500,"error":"Internal Server Error","path":"/boom"}
  接口访问 /bad:400 application/json | {"timestamp":"…","status":400,"error":"Bad Request","path":"/bad"}
  接口访问 /num/abc:400 application/json | {"timestamp":"…","status":400,"error":"Bad Request","path":"/num/abc"}

浏览器是 Whitelabel 页,接口是 4 字段 JSON。

旧 key

实测 · 本机执行输出
  server.error.include-message:标为弃用,替换为 spring.web.error.include-message
  server.error.include-stacktrace:标为弃用,替换为 spring.web.error.include-stacktrace
  server.error.whitelabel.enabled:标为弃用,替换为 spring.web.error.whitelabel.enabled
  -- 同一节的另一组配置
  接口访问 /boom,旧 key 全开:500 application/json | {"timestamp":"…","status":500,"error":"Internal Server Error","path":"/boom"}
  接口访问 /bad,旧 key 全开:400 application/json | {"timestamp":"…","status":400,"error":"Bad Request","path":"/bad"}

元数据标为弃用,实测不生效。

新 key

实测 · 本机执行输出
  接口访问 /boom:500 application/json | {"timestamp":"…","status":500,"error":"Internal Server Error","exception":"java.lang.IllegalStateException","message":"数据库连不上了","path":"/boom"}
  接口访问 /bad:400 application/json | {"timestamp":"…","status":400,"error":"Bad Request","exception":"org.springframework.web.server.ResponseStatusException","message":"id 不能为空","path":"/bad"}

message 与 exception 出现在 JSON 里。

堆栈

实测 · 本机执行输出
  接口访问 /boom,响应体里 trace 字段:500 application/json | {"timestamp":"…","status":500,"error":"Internal Server Error","trace":"<堆栈,长度超过 1000 个字符>","path":"/boom"}

include-stacktrace=always 会暴露完整堆栈。

关 Whitelabel

实测 · 本机执行输出
  浏览器访问 /nope:404 text/html | <html><body><h1>Whitelabel Error Page</h1><p>This application has no explicit mapping for /error, so you are seeing this as a fallback.</p><div id='created'>…</div><div>There was an unexpected error (type=Not Found, status=404).</div></body></html>
  -- 同一节的另一组配置
  改用 spring.web.error.whitelabel.enabled=false,浏览器访问 /nope:404 text/html | Tomcat 自带的错误页,<title>HTTP Status 404 – Not Found</title>
  同上,接口访问 /nope:404 application/json | {"timestamp":"…","status":404,"error":"Not Found","path":"/nope"}

新 key 才能关掉。

静态 404 页

实测 · 本机执行输出
  浏览器访问 /nope:404 text/html | <html><body>这是 static/error/404.html 里的自定义 404 页</body></html>
  接口访问 /nope:404 application/json | {"timestamp":"…","status":404,"error":"Not Found","path":"/nope"}
  浏览器访问 /boom(没有 5xx.html):500 text/html | <html><body><h1>Whitelabel Error Page</h1><p>This application has no explicit mapping for /error, so you are seeing this as a fallback.</p><div id='created'>…</div><div>There was an unexpected error (type=Internal Server Error, status=500).</div></body></html>

按状态码匹配,只对浏览器请求生效。

自定义 ErrorController

实测 · 本机执行输出
  浏览器访问 /nope:406  | 
  接口访问 /boom:500 application/json | {"状态":"500","自定义":"我自己的 /error 处理"}

只产生 JSON 时,浏览器请求得到 406。

分步演示

Whitelabel
本步的对象

    本文用到的工具与边界

    • 本机 macOS 27 arm64 / OpenJDK 21.0.12(Homebrew) / Spring Boot 4.0.8(Spring Framework 7.0.9、Tomcat 11.0.24) / Spring Cloud 2025.1.3;用 javac 编译、java 直接运行,依赖由 Maven 从 Maven Central 解析;数字每次运行会有小幅抖动(Spring Boot 4.0.8,spring-boot-starter-webmvc,Tomcat 11;用 Accept 请求头模拟浏览器与接口调用;属性的弃用信息取自 130 个 spring-boot 模块 jar 的配置元数据;旧 key 是否生效由响应内容判断)
    • 没有验证:server.error.path 与 spring.web.error.path 的差别;WebFlux 下的错误处理;include-binding-errors 的效果;自定义 error.html 模板(需要模板引擎);@ControllerAdvice 与 ErrorController 的先后;Boot 3.5 下旧 key 的效果(这里没有跑对照);为什么旧 key 在元数据里只标了弃用却不生效(只观察到现象)
    京ICP备2026067502号-1京公网安备11010502063487号