WSL2环境下Vite HMR无法自动更新浏览器的问题求助

在WSL2（Ubuntu）环境开发OctoberCMS/Laravel网站，使用Vite及OFFLINE的OctoberCMS Vite插件实现资源加载与HMR功能。当前Vite可正常加载资源，终端能检测到文件变化并提示页面重载（如9:52:03 AM [vite] page reload layouts/form.htm），但浏览器必须手动刷新才能看到更改。

已尝试的方案：

• 开启/关闭usePolling设置
• 服务器配置添加/移除host: 0.0.0.0
• 将HMR host设置为127.0.0.1
• 修改WSL的/etc/wsl.conf和/etc/resolv.conf配置DNS

Vite启动输出：

VITE v5.2.9  ready in 185 ms

  ➜  Local:   https://localhost:5173/themes/albums/assets/build/
  ➜  Network: https://172.31.16.20:5173/themes/albums/assets/build/
  ➜  Network: https://172.18.0.1:5173/themes/albums/assets/build/
  ➜  Network: https://172.19.0.1:5173/themes/albums/assets/build/
  ➜  press h + enter to show help

本地电脑与正常工作笔记本的区别：工作笔记本的Network行显示192.开头的IP地址。

当前Vite配置文件：

import { defineConfig } from 'vite'
import { resolve } from 'path'
import fs from 'fs'

const input = {
    css: resolve(__dirname, 'resources/css/app.css'),
    js: resolve(__dirname, 'resources/js/app.js')
}

export default defineConfig({
    base: '/themes/albums/assets/build/',
    publicDir: 'assets/static',
    build: {
        rollupOptions: { input },
        manifest: true,
        emptyOutDir: true,
        outDir: resolve(__dirname, 'assets/build'),
        assetsDir: '',
    },
    server: {
        host: '0.0.0.0',
        https: {
            key: fs.existsSync('/ca/localhost-key.pem') ? fs.readFileSync('/ca/localhost-key.pem', 'utf-8') : '',
            cert: fs.existsSync('/ca/localhost.pem') ? fs.readFileSync('/ca/localhost.pem', 'utf-8') : '',
        },
        hmr: {
            host: 'localhost'
        },
        watch: {
            usePolling: true
        }
    }
});

1. 配置HMR指向WSL2的实际局域网IP #

WSL2默认使用NAT网络模式，localhost在宿主机和WSL内的映射可能导致HMR的WebSocket连接失败。需要将HMR指向WSL2的局域网IP：

• 在WSL终端执行以下命令获取当前局域网IP：

  hostname -I | awk '{print $1}'
  

  得到类似172.31.16.20的IP（对应Vite启动输出中的Network IP）。

• 修改Vite配置中的server.hmr部分：

  server: {
      host: '0.0.0.0',
      https: {
          // 保持原有的证书配置
          key: fs.existsSync('/ca/localhost-key.pem') ? fs.readFileSync('/ca/localhost-key.pem', 'utf-8') : '',
          cert: fs.existsSync('/ca/localhost.pem') ? fs.readFileSync('/ca/localhost.pem', 'utf-8') : '',
      },
      hmr: {
          host: '172.31.16.20', // 替换为你的WSL2局域网IP
          clientPort: 5173 // 明确指定客户端端口，确保宿主机能访问
      },
      watch: {
          usePolling: true
      }
  }
  

• 重启Vite服务，浏览器访问网站时，检查控制台Network面板中，WebSocket连接（路径类似wss://172.31.16.20:5173/）是否成功建立。

2. 同步OctoberCMS Vite插件配置 #

确保OFFLINE Vite插件的配置指向正确的HMR地址：

• 在OctoberCMS的插件设置中，将Vite Server URL设置为https://你的WSL2IP:5173（而非localhost）。
• 清除OctoberCMS的缓存，确保插件加载最新的Vite配置。

3. 配置宿主机Hosts映射（可选） #

如果不想每次WSL重启后修改IP（WSL2重启后IP可能变化），可以在宿主机的Hosts文件中添加固定映射：

• 在Windows系统中，打开C:\Windows\System32\drivers\etc\hosts（需管理员权限），添加一行：

  172.31.16.20 wsl-local
  

  替换IP为你的WSL2局域网IP，wsl-local是自定义域名。

• 修改Vite配置：

  server: {
      host: 'wsl-local',
      hmr: {
          host: 'wsl-local'
      },
      // 其他配置保持不变
  }
  

• 浏览器访问网站时使用https://wsl-local:8000（假设Laravel/OctoberCMS的服务端口是8000），Vite的HMR会通过这个域名建立连接。

4. 确保端口访问权限 #

• 在WSL终端中允许5173端口的TCP访问：

  sudo ufw allow 5173/tcp
  

• 检查宿主机防火墙是否放行5173端口，避免拦截WebSocket连接。

5. 切换WSL2网络模式为桥接（进阶） #

如果上述方法无效，可以尝试将WSL2的网络模式改为桥接，让WSL获取与宿主机同网段的192.开头IP（和你的工作笔记本一致）：

• 在Windows终端（管理员权限）执行：

  wsl --shutdown
  wsl --set-default-version 2
  wsl --distribution Ubuntu --set-net-bridge "以太网" # 替换"以太网"为你的网卡名称
  

• 重启WSL，此时Vite启动的Network IP会变成192.开头，HMR连接会更稳定。

工作笔记本的192.开头IP是因为其WSL可能使用了桥接网络模式，与宿主机在同一局域网段，HMR的WebSocket连接能直接建立。而你的本地电脑使用WSL2默认的NAT模式，localhost的端口转发存在限制，导致浏览器无法接收到HMR的重载信号。

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