排查了一整天最后只加了一个注解。问 AI 查文章得到的答案不是劝你升级降级版本就是让你改一堆配置文件绕了一大圈其实一个注解就能解决。背景有时候项目迭代升级后文档页面突然白屏控制台还冒出NoSuchMethodError之类的报错。很多人第一反应是“版本不兼容”于是想着升级 springdoc、降级 Spring Boot……可生产环境里版本往往是定死的动一发牵全身根本不敢随便改。我前两天也踩了这个坑折腾很久发现根本不用动版本只要给全局异常处理器加一个Hidden注解问题就解决了。一、环境信息维度版本Spring Boot3.5.xSpring Framework 6.2.xJava 17Knife4jknife4j-openapi3-jakarta-spring-boot-starter 4.1.0内置 springdoc 1.7.0注解体系OpenAPI 3io.swagger.v3.oas.annotations二、问题现象2.1 页面表现访问doc.html页面白屏/报错右上角提示“Knife4j 文档请求异常”接口列表加载不出来效果如下2.2 前端控制台F12报错打开浏览器 F12 看 Network 与 Console能看到这样一串报错v3/api-docs:1 Failed to load resource: the server responded with a status of 500 () app.30e79dc0.js:1 Error: Request failed with status code 500 at e.exports (chunk-vendors.d59642c5.js:2:679693) at e.exports (chunk-vendors.d59642c5.js:2:1298909) at XMLHttpRequest.y (chunk-vendors.d59642c5.js:2:1868675)关键信息就两条/v3/api-docs返回500文档页加载的核心数据请求失败了app.30e79dc0.js报Request failed with status code 500前端拿不到合法数据自然渲染不出文档页2.3 后端控制台报错真正的原因在后端控制台报错如下jakarta.servlet.ServletException: Handler dispatch failed: java.lang.NoSuchMethodError: void org.springframework.web.method.ControllerAdviceBean.init(java.lang.Object) Caused by: java.lang.NoSuchMethodError: void org.springframework.web.method.ControllerAdviceBean.init(java.lang.Object) at org.springdoc.core.service.GenericResponseService...三、关键复现一个注解让文档恢复项目里有这样一个全局异常处理器RestControllerAdvice public class GlobalExceptionAdvice { ExceptionHandler public ResponseEntity? handleWoNiuHealthException(WoNiuHealthException e) { e.printStackTrace(); return ResponseEntity.status(500) .body(Map.of(code, 500, message, e.getMessage())); } ExceptionHandler public ResponseEntity? handleException(Exception e) { e.printStackTrace(); return ResponseEntity.status(500) .body(Map.of(code, 500, message, e.getMessage())); } }实测状态现象去掉Hiddendoc.html白屏/v3/api-docs报NoSuchMethodError加上Hidden文档恢复正常四、根因说明为什么不是版本不兼容很多人在看到NoSuchMethodError时会下意识认为是springdoc 版本太老不兼容 Spring Framework 6.2.x于是急着去升级依赖。但这次的问题其实不是版本兼容性问题而是Springdoc 内部扫描机制触发了对ControllerAdviceBean构造方法的调用而这个调用在特定条件下才会出问题。关键点在于Springdoc 在生成 OpenAPI 规范时会扫描所有标注了RestControllerAdvice的类并尝试将它们包装成ControllerAdviceBean进行处理。在 Spring Framework 6.2.x 中ControllerAdviceBean的构造方法签名发生了变化而 springdoc 1.7.0 在某些场景下比如遇到ResponseEntity?这种需要复杂类型解析的情况会调用旧版本的构造方法从而抛出NoSuchMethodError。这个报错是Error而不是Exception所以ExceptionHandler(Exception e)根本接不住它只能眼睁睁看着它往上抛。结论问题不在于“版本不兼容”而在于Springdoc 在扫描全局异常处理器时触发了不兼容的方法调用。只要让 Springdoc 跳过对全局异常处理器的扫描就能完美规避这个问题而不需要动任何版本。五、我的解决方法什么都不用改只加一个注解import io.swagger.v3.oas.annotations.Hidden; RestControllerAdvice Hidden // 让 Springdoc 忽略该类 public class GlobalExceptionAdvice { // ... 异常处理方法 }就这一个注解。原理很简单Hidden通知 Springdoc完全忽略这个类不再扫描它、不做 Advice 包装、不解析返回类型那串触发NoSuchMethodError的代码直接不执行/v3/api-docs正常生成doc.html立刻恢复。六、为什么我推荐它而不是升级/降级版本方案成本风险升级/降级 Spring Boot 或 springdoc高需回归测试、协调团队高可能引入新问题加Hidden注解极低一行代码极低只影响文档扫描可以说这是当前成本和风险都最低的解法也是我最想分享给同样踩坑的朋友的做法。