Vaadin 24升级报错：window.Vaadin.Flow.loadOnDemand不是函数

核心原因分析 #

这个错误说明前端运行时找不到loadOnDemand方法，本质是跨版本升级后前端资源不兼容或生产模式打包时旧资源未彻底清理/更新——Vaadin 14到24的前后端资源架构差异极大，旧资源残留会直接引发这类API不匹配问题。

具体排查修复步骤 #

• 彻底清理前端缓存与旧资源

  1. 删除项目根目录下的node_modules、package-lock.json（或yarn.lock）文件
  2. 执行Vaadin专属清理命令：Maven项目用mvn vaadin:clean-frontend，Gradle项目用gradle cleanFrontend
  3. 重新构建前端资源：Maven执行mvn vaadin:build-frontend，Gradle执行gradle buildFrontend
  4. 生产打包时务必使用全新构建产物，禁止复用旧打包文件

• 检查依赖是否完全升级

  1. 确认所有Vaadin相关依赖（含附加组件）都升级到24.3.5版本，排查pom.xml或build.gradle中是否残留com.vaadin:vaadin-core:14.x.x这类旧依赖
  2. 检查自定义前端代码（如自定义JS、CSS），loadOnDemand是Vaadin 14的专属前端方法，在Vaadin 24中已被移除或替换，需更新代码适配新API

• 验证生产打包配置

  1. 确认vaadin-maven-plugin（或Gradle插件）版本为24.3.5，且productionMode配置正确
  2. 排查是否有自定义打包脚本（如Webpack配置）覆盖了Vaadin默认生产打包流程，导致前端资源未正确生成或合并

• 清除浏览器缓存
  生产环境部署后，强制刷新浏览器缓存（Ctrl+Shift+R），避免加载本地缓存的Vaadin 14旧资源

补充说明 #

Vaadin 24的前端架构已从Vaadin 14的Polymer迁移到Lit，前端运行时API变化巨大，旧代码或缓存资源极易引发兼容性问题。必要时可删除vaadin-frontend目录后重新生成，确保无旧文件残留。

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