CRA迁移Vite后热更新失效触发整页刷新如何解决

按以下优先级排查调整配置，即可解决Vite开发时频繁全量重载的问题：

1. 修正配置文件的模块语法与路径解析逻辑 #

当前配置混用ESM与CommonJS语法，ESM环境下直接使用__dirname会导致别名路径解析异常，Vite无法正确构建模块依赖树，直接导致HMR失效触发整页刷新。
替换配置头部的路径引入与别名计算代码：

import { defineConfig, loadEnv } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'node:path'
import { fileURLToPath } from 'node:url'

const __dirname = path.dirname(fileURLToPath(import.meta.url))
const aliases = {
  '@Form': 'src/Components/Form/Exports',
  '@List': 'src/Components/List/Exports',
  '@Browse': 'src/Components/Browse/Browse',
  '@Tree': 'src/Components/Tree/Exports',
  '@Tab': 'src/Components/Tab/Exports',
  '@Dashboard': 'src/Components/Dashboard/Dashboard',
  '@Panel': 'src/Panel/Panel',
}

const resolvedAliases = Object.fromEntries(
  Object.entries(aliases).map(([key, value]) => [key, path.resolve(__dirname, value)]),
)

2. 修复自定义HTML转换插件的缓存逻辑 #

手写的html-transform插件未声明依赖追踪规则，会导致Vite每次文件变更都判定index.html被修改，直接触发整页刷新。
优先使用Vite原生能力替换自定义插件：移除手写的htmlPlugin代码，在配置中添加envPrefix: ''即可支持HTML中读取通过loadEnv导入的环境变量，占位符保持%变量名%格式即可。
如果需要兼容非VITE_前缀的环境变量必须保留自定义插件，需要给插件添加强缓存声明，避免无意义的重复转换：

const htmlPlugin = (env, mode) => {
  return {
    name: "html-transform",
    transformIndexHtml: {
      order: 'pre',
      handler(html) {
        return html.replace(/%(.*?)%/g, (match, p1) => env[p1] ?? '')
      },
      dependencies: [path.resolve(__dirname, `.env`), path.resolve(__dirname, `.env.${mode}`)]
    }
  }
}
// 调用时传入mode参数
plugins: [react(), htmlPlugin(env, mode)]

3. 调整React插件配置适配Barrel导出 #

别名指向的Exports文件属于Barrel导出文件（集中导出多个模块的索引文件），这类文件容易打破React Fast Refresh的更新边界，需要显式配置插件的文件匹配范围：

plugins: [
  react({
    include: /\.(js|jsx|ts|tsx)$/,
    exclude: /node_modules/
  }),
  // 其余插件
]

4. 修正HMR连接配置 #

强制设置hmr.clientPort: 443仅适用于HTTPS反向代理的开发场景，本地直接启动服务时该配置会导致HMR WebSocket连接失败，Vite检测到连接异常后会自动降级为整页刷新。

• 本地直接启动开发服务：删除hmr下的clientPort配置，使用默认值即可
• 走HTTPS代理启动：补全HMR的协议、域名配置，确保WebSocket连接正常：

server: {
  host: '0.0.0.0',
  hmr: {
    protocol: 'wss',
    host: '本地开发访问域名',
    clientPort: 443
  }
}

启动后打开浏览器控制台，出现[vite] connected日志且无WebSocket连接报错即为正常。

5. 剩余边界场景排查 #

完成以上配置调整后如果仍存在非预期全刷，打开浏览器控制台查看Vite打印的刷新触发原因，常见场景如下：

• 修改的文件同时导出React组件和普通常量、工具函数，超出Fast Refresh支持范围，将非组件逻辑拆分到独立的工具文件即可
• 项目存在循环依赖，Vite无法做增量更新，可通过启动日志排查循环依赖的文件，调整导入路径解决
• 修改vite.config.js、.env等配置文件触发的全刷属于Vite的正常行为，不需要额外处理

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