Vaadin 24升级后运行抛出ClassNotFoundException: org.jsoup.nodes.Node

问题描述 #

按照《从Vaadin 23升级》指南完成项目升级后，项目可正常构建，但运行时抛出如下异常：

发送上下文初始化事件至监听器实例[com.vaadin.flow.spring.VaadinServletContextInitializer$CompositeServletContextListener]时出错
at com.vaadin.flow.server.startup.VaadinAppShellInitializer.init(VaadinAppShellInitializer.java:96)
Caused by: java.lang.ClassNotFoundException: org.jsoup.nodes.Node
at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:520)

原因 #

该异常说明项目运行时缺失jsoup依赖——org.jsoup.nodes.Node是jsoup库的核心类，Vaadin的App Shell初始化、HTML解析等功能依赖这个库。升级过程中可能因依赖版本调整、依赖被主动排除，或是构建配置问题，导致jsoup未被正确加入运行时类路径。

解决步骤 #

• 检查并添加jsoup依赖：
  根据项目使用的构建工具，确保引入兼容Vaadin 23的jsoup版本：
  • Maven项目，在pom.xml中添加：

    <dependency>
        <groupId>org.jsoup</groupId>
        <artifactId>jsoup</artifactId>
        <!-- 推荐使用1.15.3版本，与Vaadin 23兼容 -->
        <version>1.15.3</version>
        <scope>runtime</scope>
    </dependency>
    

  • Gradle项目，在build.gradle中添加：

    runtimeOnly 'org.jsoup:jsoup:1.15.3'
    

• 排查依赖排除规则：
  检查项目中是否有其他依赖通过<exclusions>（Maven）或exclude（Gradle）排除了jsoup，若存在则移除对应的排除配置。
• 清理重建项目：
  执行构建工具的清理构建命令（Maven：mvn clean install；Gradle：./gradlew clean build），确保依赖被正确下载并打包到运行环境中。

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