Tomcat10部署ZK框架war包报HttpSessionListener类未找到错误

问题根因 #

该报错的核心诱因是Tomcat 10及以上版本全面切换至Jakarta EE 9+规范，原javax.servlet系列包全量重命名为jakarta.servlet包，低于9.6.0版本的ZK框架仅适配旧版javax.servlet接口，无法兼容Tomcat10的包结构，即使手动补全旧监听器依赖也无法正常加载。

对应报错日志：
java.lang.ClassNotFoundException: org.zkoss.zk.ui.http.HttpSessionListener

解决方案 #

按以下步骤依次操作即可解决适配冲突：

• 第一步：将项目使用的ZK框架版本升级至9.6.0及以上正式版，仅该版本段的ZK提供Jakarta EE（Tomcat10+）的官方适配支持。
• 第二步：修改项目web.xml中的监听器配置，将原来的旧监听器类org.zkoss.zk.ui.http.HttpSessionListener替换为适配Jakarta规范的新监听器类org.zkoss.zk.ui.http.JakartaHttpSessionListener。
• 第三步：校验项目的打包配置，确认所有ZK相关依赖jar包已完整打入war包的WEB-INF/lib目录，排除依赖缺失问题。
• 第四步：清理Tomcat缓存目录，删除/opt/tomcat/work/Catalina/localhost/下对应项目的缓存文件夹，重启Tomcat即可正常启动。

额外注意事项 #

如果完成上述操作后仍出现类缺失报错，需全局检查项目代码及第三方依赖，确认所有引入javax.servlet.*的代码全部替换为jakarta.servlet.*的对应类，且所有第三方依赖均已完成Jakarta EE规范适配。

内容的提问来源于stack exchange，提问作者Cindy Estefanía Miranda Campos