Vite(v5.1.3)后端集成开发模式出现__HMR_CONFIG_NAME__未定义错误求助

可能的原因及对应解决方案 #

1. 检查HTML入口模板的Vite客户端注入代码 #

后端集成模式下需手动在HTML中注入Vite开发客户端脚本，确保脚本路径和配置正确：

• 确认注入的是Vite自动生成的开发客户端脚本，而非生产构建脚本
• 正确注入格式（以Node.js后端为例）：

  <% if (isDev) { %>
    <script type="module" src="http://localhost:5173/@vite/client"></script>
  <% } %>
  

  注意：__HMR_CONFIG_NAME__是Vite HMR内部变量，由@vite/client自动定义，不要手动修改或删除相关代码。

2. 排查Vite配置中的HMR相关设置 #

• 检查vite.config.js的server.hmr配置，避免错误覆盖默认HMR规则：

  export default defineConfig({
    server: {
      hmr: {
        host: 'localhost',
        port: 5173,
        // 不要随意禁用clientPort或设置错误路径
      }
    }
  })
  

• 若后端使用反向代理，确保Vite的HMR请求能正确转发到开发服务器，避免请求被后端拦截导致客户端脚本加载不完整。

3. 清理缓存并重启服务 #

• 清除浏览器缓存（快捷键Ctrl+Shift+R或Cmd+Shift+R），避免加载旧脚本缓存
• 完全关闭Vite开发服务器和后端服务后重新启动
• 清除Vite缓存目录并重装依赖：

  rm -rf node_modules/.vite
  npm install
  

4. 排查自定义HMR插件或脚本冲突 #

• 若项目使用自定义HMR插件或手动编写HMR相关代码，检查是否误修改了Vite内置HMR变量
• 暂时禁用第三方插件，逐步排查是否为插件导致的冲突

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