Shopify Hydrogen本地开发服务器ERR_CONNECTION_RESET问题求助

针对你在Windows 10的WSL2（Ubuntu 24.04）环境中，Hydrogen开发服务正常启动但Windows浏览器访问localhost:3000报错的问题，给你几个具体的排查方向：

• 强制Hydrogen绑定所有网卡地址
  默认Hydrogen可能只绑定WSL本地的127.0.0.1，导致Windows主机无法访问。修改启动方式：

  • 直接在启动命令后加参数：npm run dev -- --host 0.0.0.0
  • 或者修改项目package.json里的dev脚本为："dev": "hydrogen dev --host 0.0.0.0"
    启动后命令行会显示http://0.0.0.0:3000，此时可以用WSL的内网IP（比如172.x.x.x）在Windows浏览器访问，或者再试localhost。

• 手动配置WSL端口转发
  WSL的自动端口转发偶尔会失效，手动设置一下：

  1. 在WSL终端执行ip addr show eth0，找到inet字段对应的IP（类似172.17.xx.xx）
  2. 打开Windows管理员权限的PowerShell，执行：

     netsh interface portproxy add v4tov4 listenport=3000 listenaddress=0.0.0.0 connectport=3000 connectaddress=你的WSL内网IP
     

  3. 同时确保Windows防火墙允许3000端口的TCP入站连接，或者临时关闭防火墙测试。

• 检查Hydrogen/Vite配置文件
  打开项目根目录的vite.config.ts，添加明确的server配置：

  import {defineConfig} from 'vite';
  import hydrogen from '@shopify/hydrogen/plugin';
  
  export default defineConfig({
    plugins: [hydrogen()],
    server: {
      host: '0.0.0.0',
      port: 3000,
    },
  });
  

  保存后重启开发服务再试。

• 排查服务本身是否正常
  在WSL内部安装轻量浏览器（比如sudo apt install firefox），启动后访问localhost:3000：

  • 如果能打开，说明问题出在WSL和Windows的网络互通上，重点查端口转发和防火墙；
  • 如果也打不开，说明Hydrogen服务有问题，删除node_modules和package-lock.json，重新执行npm install后再启动服务。

• 检查杀毒软件拦截
  部分第三方杀毒软件会拦截本地开发端口，临时关闭杀毒软件后测试访问，若正常则需要在杀毒软件里添加3000端口的放行规则。

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