Hilla集成现有Spring Boot应用时Vite无法启动如何排查

日志中出现http://localhost:0是核心定位线索：端口0是系统用于随机分配临时端口的占位符，出现该地址说明Vite开发服务器根本没有完成启动流程，没有将实际监听的有效端口回传给Spring Boot侧的Hilla集成逻辑，后续的连接异常是这个问题的结果，而非原因。
可按以下顺序逐一排查：

• 先确认前端依赖安装完整。不要仅拷贝初始化项目的package.json、vite.config.ts等配置文件就启动应用，先在项目根目录执行对应包管理器的安装命令（npm执行npm install、pnpm执行pnpm install），同时确认本地Node版本符合当前Hilla版本要求（Hilla 2.x要求Node 18.13及以上）。多数集成场景下Vite进程启动瞬间退出，都是因为依赖缺失、Node版本不兼容导致，此时Spring Boot侧拿不到有效端口，就会默认用0端口发起请求。
• 检查pom.xml中Hilla/Vaadin构建插件的生命周期绑定是否正确。引入的hilla-maven-plugin/vaadin-maven-plugin必须绑定到process-classes阶段，确保开发态下会执行prepare-frontend目标拉起Vite进程。如果把插件配置放到了production专属profile下，或者现有项目自定义了构建生命周期跳过了该阶段，Vite进程根本不会被触发启动。
• 核对开发服务相关配置与安全规则。检查application.properties/application.yml中是否存在误配：vaadin.devserver.enabled在开发态必须为true，不要手动指定vaadin.devserver.port=0。另外因为你集成了认证模块，要确认Spring Security配置中放通了Hilla前端开发的内置路径：/VAADIN/**、/frontend/**、/hilla/**需要配置为permitAll()，如果这些路径被认证拦截，Spring Boot侧探测Vite端口的内部请求会被拦截，也会拿不到有效端口。
• 开启前端模块调试日志查看Vite实际退出原因。在配置文件中添加logging.level.com.vaadin.flow.server.frontend=DEBUG，重启后搜索日志中Frontend相关输出，会直接打印Vite进程的启动命令、标准输出、错误输出。常见问题是拷贝的vite.config.ts中前端入口路径和现有项目目录结构不匹配（比如现有项目没有默认的frontend/目录、入口文件路径不对），Vite启动时找不到资源直接退出，默认日志级别下不会打印这部分报错。
• 确认Hilla自动配置是否正常加载。检查添加了@Theme、@PWA注解、实现了AppShellConfigurator接口的启动类，是否在Spring Boot的组件扫描范围内，如果自定义了@ComponentScan规则把Hilla的自动配置类、启动类本身排除了，Vite启动逻辑根本不会触发。可以在启动日志中搜索Starting Vite dev server关键字，如果完全搜不到对应日志，就说明自动配置未生效。

注意：不要在java.net.ConnectException连接异常本身消耗排查精力，这个异常只是尝试连接0端口的必然结果，核心排查逻辑始终围绕「Vite进程为什么没正常启动」「Spring Boot为什么没拿到Vite的有效监听端口」两个方向展开即可。

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