从vue-cli迁移至Vite后热更新出现Cannot read properties of null报错

问题背景 #

按教程完成Vue 3项目从vue-cli到Vite的迁移后，项目能正常启动运行，但修改组件并保存后，浏览器控制台抛出错误，页面直接空白，刷新后错误消失、修改内容正常显示。

错误信息 #

Uncaught (in promise) TypeError: Cannot read properties of null (reading 'nextSibling')

项目配置 #

package.json #

{    
  "name": "vue-project",    
  "version": "0.1.0",    
  "private": true,    
  "scripts": {        
    "dev": "vite",        
    "build": "vite build",        
    "preview": "vite preview",        
    "format": "prettier . --write"    
  },    
  "dependencies": {        
    "@fortawesome/fontawesome-free": "^6.5.1",        
    "@vitejs/plugin-vue": "^5.0.4",        
    "@vueuse/core": "^10.9.0",        
    "chart.js": "^4.4.2",        
    "dayjs": "^1.11.10",        
    "firebase": "^10.9.0",        
    "firebase-admin": "^12.1.0",        
    "pinia": "^2.1.7",        
    "primeicons": "^6.0.1",        
    "primevue": "^3.50.0",        
    "register-service-worker": "^1.7.2",        
    "vite": "^5.2.11",        
    "vue": "^3.2.39",        
    "vue-chartjs": "^5.3.1",        
    "vue-router": "^4.0.3"    
  },    
  "devDependencies": {        
    "autoprefixer": "^10.4.18",        
    "postcss": "^8.4.37",        
    "prettier": "^2.8.8",        
    "tailwindcss": "^3.4.1"    
  }
}

vite.config.mjs #

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import { fileURLToPath } from "url";
import path from "path";

const filename = fileURLToPath(import.meta.url);
const pathSegments = path.dirname(filename);

export default defineConfig({    
  resolve: {        
    alias: {            
      "@": path.resolve(pathSegments, "./src")        
    },        
    extensions: [".mjs", ".js", ".ts", ".jsx", ".tsx", ".json"]    
  },    
  plugins: [vue()]
});

解决方案 #

这个错误大多和Vite热模块替换（HMR）与第三方依赖的兼容性有关，结合你的依赖列表，按以下顺序排查：

1. 升级Vue核心版本
   当前Vue版本3.2.39较老，存在已知的HMR相关bug。直接升级到最新稳定版：

   npm install vue@latest
   

2. 排查PrimeVue的HMR兼容性
   PrimeVue部分版本和Vite HMR存在冲突，先升级到最新版：

   npm install primevue@latest primeicons@latest
   

   若升级后问题依旧，可在Vite配置中标记PrimeVue组件为自定义元素，跳过HMR处理：

   // vite.config.mjs
   export default defineConfig({
     // ...其他配置
     plugins: [
       vue({
         template: {
           compilerOptions: {
             isCustomElement: (tag) => tag.startsWith('p-')
           }
         }
       })
     ]
   });
   

3. 临时禁用Service Worker
   项目中引入的register-service-worker可能缓存旧资源干扰HMR，开发环境下可先注释掉src/main.js中注册SW的代码，或者在Vite配置中排除SW的预构建：

   // vite.config.mjs
   export default defineConfig({
     // ...其他配置
     optimizeDeps: {
       exclude: ['register-service-worker']
     }
   });
   

4. 检查Vue Router的HMR配置
   确保路由文件使用动态导入，并在开发环境启用HMR：

   // router/index.js
   import { createRouter, createWebHistory } from 'vue-router'
   
   const routes = [
     {
       path: '/',
       name: 'Home',
       component: () => import('../views/Home.vue') // 使用动态导入
     }
   ]
   
   const router = createRouter({
     history: createWebHistory(process.env.BASE_URL),
     routes
   })
   
   // 开发环境启用路由HMR
   if (import.meta.hot) {
     import.meta.hot.accept()
   }
   
   export default router
   

5. 清理缓存重启服务
   删除依赖包和锁文件，重新安装后启动服务：

   rm -rf node_modules package-lock.json
   npm install
   npm run dev
   

总结 #

优先尝试升级Vue和PrimeVue版本，这是解决此类HMR兼容性问题最直接的方案。如果问题仍存在，再逐步排查Service Worker、路由配置等因素。

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