M1芯片MacOS 12 Monterey下Vaadin开发模式Webpack连接报错

核心故障原因 #

该问题是MacOS 12 Monterey系统的默认网络配置与Vaadin 21版本开发模式的webpack dev server监听逻辑不兼容导致：

• 生产模式运行正常是因为生产模式不会启动本地webpack dev server，直接使用预编译完成的前端静态资源，无需本地服务间通信
• 开发模式下，webpack dev server默认仅监听IPv4地址127.0.0.1，但Monterey系统默认将localhost域名优先解析为IPv6地址::1，导致Java侧的DevModeHandler尝试通过localhost连接webpack dev server时被拒绝，抛出Connection refused报错。

排查步骤 #

• 查看本地hosts配置，执行cat /etc/hosts确认是否存在::1 localhost配置项，且优先级高于127.0.0.1 localhost
• 项目启动到报错阶段时，执行lsof -i -P | grep node查看webpack dev server实际监听的地址是IPv4还是IPv6
• 尝试直接通过http://127.0.0.1:<webpack端口>/manifest.json访问，确认服务是否正常监听IPv4地址

解决方案 #

方案1（推荐，无需修改系统配置） #

在IntelliJ的项目运行配置中，VM options添加参数-Djava.net.preferIPv4Stack=true，强制Java进程优先使用IPv4协议发起网络请求，适配webpack dev server的监听配置。

方案2（修改Vaadin配置） #

在项目的application.properties（或application.yml）中添加配置：
vaadin.devmode.host=::1
强制webpack dev server监听IPv6的localhost地址，匹配系统的默认解析规则。

方案3（修改系统hosts优先级） #

编辑/etc/hosts文件，将127.0.0.1 localhost行调整到::1 localhost行之前，修改完成后执行sudo dscacheutil -flushcache刷新DNS缓存即可。

方案4（版本升级） #

升级到Vaadin 21的最新维护版本，该版本已经针对MacOS Monterey的解析逻辑做了兼容修复，无需额外配置即可正常运行。

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