Vaadin 23路由异常：访问任意URL均返回空白index.html页面

问题背景 #

项目环境：

• Java 17
• Spring MVC 5.3.20
• Apache Tomcat 8.5.85
• 依赖管理：Ivy + Ant

已完成配置：

1. web.xml中配置了VaadinServlet
2. Spring上下文定义了Vaadin应用配置Bean：

<context:annotation-config/>
<bean class="com.vaadin.flow.spring.VaadinApplicationConfiguration"/>

编写的测试View代码：

@Route("vaadin/test")
public class TestView extends HorizontalLayout {
    private TextField name;
    private Button sayHello;
    public TestView() {
        name = new TextField("Your name");
        sayHello = new Button("Say hello");
        sayHello.addClickListener(e -> Notification.show("Hello " + name.getValue()));
        sayHello.addClickShortcut(Key.ENTER);
        setMargin(true);
        setVerticalComponentAlignment(Alignment.END, name, sayHello);
        add(name, sayHello);
    }
}

问题现象：访问/vaadin/test或任意URL，均返回META-INF/VAADIN/webapp下的空白index.html，无法加载测试View。

排查与解决步骤 #

1. 修正VaadinServlet的映射配置 #

检查web.xml中VaadinServlet的<url-pattern>，确保能覆盖目标路由路径。推荐配置：

<servlet>
    <servlet-name>VaadinServlet</servlet-name>
    <servlet-class>com.vaadin.flow.spring.SpringServlet</servlet-class>
</servlet>
<servlet-mapping>
    <servlet-name>VaadinServlet</servlet-name>
    <url-pattern>/vaadin/*</url-pattern>
</servlet-mapping>

如果需要Vaadin接管所有请求，可添加<url-pattern>/*</url-pattern>，但需注意和Spring MVC的DispatcherServlet路径冲突，建议两者路径明确划分（比如Spring MVC处理/api/*，Vaadin处理/vaadin/*）。

2. 确保Spring组件扫描覆盖测试View #

Spring需要扫描到带有@Route注解的View类，在Spring配置文件中添加组件扫描：

<context:component-scan base-package="com.your.view.package"/> <!-- 替换为TestView所在的包路径 -->

若组件未被扫描，Vaadin无法注册该路由，会 fallback到空白index.html。

3. 检查前端资源构建完整性 #

Vaadin 23依赖前端资源（JS、初始化脚本等），空白index.html通常意味着前端构建未完成：

• 确认Ant构建脚本中集成了Vaadin的前端构建任务（如vaadinBuildFrontend），执行该任务生成完整的index.html及相关资源
• 查看META-INF/VAADIN/webapp下的index.html，正常情况下应包含Vaadin初始化代码，而非空白内容

4. 调整Servlet映射优先级 #

Tomcat中Servlet按映射顺序匹配，若Spring MVC的DispatcherServlet映射路径和Vaadin重叠，且优先级更高，会导致Vaadin无法处理请求。确保VaadinServlet的映射配置在DispatcherServlet之前，或调整两者路径避免重叠。

5. 验证Java与Tomcat兼容性 #

Tomcat 8.5官方仅支持Java 7至14，你使用的Java 17超出其兼容范围，可能导致请求处理异常。建议：

• 降级Java版本至11或14
• 升级Tomcat至9.x及以上版本（支持Java 17）

6. 开启DEBUG日志排查细节 #

开启Vaadin的DEBUG级别日志，查看：

• VaadinApplicationConfiguration是否成功加载
• TestView是否被注册为路由
• 是否存在资源加载失败、路由匹配失败的隐藏错误

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