升级 vaadin 23.3.5 后路由失效、返回 whitelabel error page，根本原因是 spring boot 版本过低——vaadin 23.3.x 要求 spring boot ≥ 2.7.0，而原项目停留在 2.6.7，导致 flow 的前端路由注册与后端请求处理链未正确初始化。
Vaadin 23 是一个重大架构演进版本，其底层依赖（尤其是 flow-server 和 flow-spring-addon）与 Spring Boot 的集成机制发生了关键变化。最易被忽略却最具破坏性的兼容性约束是：Vaadin 23.3.x（含 23.3.5）强制要求 Spring Boot 2.7.0 或更高版本。尽管官方升级指南曾错误标注最低支持版本为 Spring Boot 2.6.6（该笔误已在后续更新中修正），但实际运行时，Spring Boot 2.6.x 系列无法正确注册 Vaadin 的 VaadinServlet, RouteRegistry, 以及关键的 IndexHtmlRequestHandler —— 这直接导致所有 @Route 标记的视图无法被识别，HTTP 请求绕过 Vaadin 路由处理器，最终落入 Spring MVC 默认的静态资源/错误处理链，触发 404 Whitelabel 页面。
✅ 正确解决方案
将 spring-boot-starter-parent 升级至 2.7.18（推荐 LTS 版本）或更高（如 2.7.19、3.0.x+ 若已适配 Spring Boot 3）：
<!-- pom.xml -->
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.7.18</version> <!-- ✅ 必须 ≥ 2.7.0 -->
<relativePath/>
</parent>同时确保 vaadin-bom 和插件版本对齐（无需额外添加 flow-maven-plugin 依赖，它已由 vaadin-bom 管理）：
使用 ImageMagick 的 convert 和 mogrify 命令进行批量图像处理，支持调整大小、裁剪、水印和格式转换。与 libvips 集成以实现高性能缩略图生成。
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.vaadin</groupId>
<artifactId>vaadin-bom</artifactId>
<version>23.3.5</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>⚠️ 关键注意事项
-
不要手动添加 flow-maven-plugin 作为
：它是构建插件，应声明在 下，且 Vaadin 官方推荐使用 vaadin-maven-plugin（v23+ 已统一）： <plugin> <groupId>com.vaadin</groupId> <artifactId>vaadin-maven-plugin</artifactId> <version>23.3.5</version> </plugin> - 清理必须彻底：执行 mvn clean, 删除 node_modules, package-lock.json, target, 并重置 npm cache（npm cache clean --force），再运行 mvn vaadin:prepare-frontend && mvn compile。
- 禁用 ErrorMvcAutoConfiguration 仅用于诊断：生产环境切勿保留 spring.autoconfigure.exclude=...ErrorMvcAutoConfiguration，它会掩盖真实异常；真正有效的日志需开启 logging.level.com.vaadin=DEBUG。
- @PermitAll 不是路由生效前提：Spring Security 配置影响访问控制，但不决定路由是否被 Vaadin 发现；若 ServiceInitEvent 监听器完全未触发，说明 Vaadin 初始化流程根本未启动——这正是 Spring Boot 版本不兼容的典型表现。
? 验证是否修复
启动应用后，检查日志中是否出现：
INFO c.v.f.s.VaadinServletContextInitializer - Registering Vaadin servlet DEBUG c.v.f.r.RouteRegistry - Registered route for class com.example.MyView
并访问 / 或任意 @Route("my-view") 路径，确认返回对应视图而非 404。
归根结底，Vaadin 23 的模块化与构建体系（Vite 替代 Webpack、服务端路由注册时机变更）深度绑定 Spring Boot 2.7 引入的 ApplicationContextInitializer 增强机制。跳过此版本门槛，任何前端配置或安全注解调整均属徒劳。务必以 Spring Boot 版本升级为第一修复动作。
