WSL中Ubuntu环境下Vite+React+Ts的HMR功能失效问题

问题描述 #

在WSL的Ubuntu环境下，修改项目文件并保存后，Vite开发服务器无法自动触发页面重新渲染，必须手动按r+enter重启服务器才生效。但相同项目在Windows的PowerShell中运行时，热更新功能完全正常。

项目配置文件 #

package.json #

{
  "name": "vite-project",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "main": "dist/index.js",
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
    "preview": "vite preview",
    "test": "tsc && jest"
  },
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  },
  "devDependencies": {
    "@babel/preset-typescript": "^7.24.1",
    "@types/jest": "^29.5.12",
    "@types/react": "^18.2.66",
    "@types/react-dom": "^18.2.22",
    "@typescript-eslint/eslint-plugin": "^7.2.0",
    "@typescript-eslint/parser": "^7.2.0",
    "@vitejs/plugin-react": "^4.2.1",
    "autoprefixer": "^10.4.19",
    "eslint": "^8.57.0",
    "eslint-plugin-react-hooks": "^4.6.0",
    "eslint-plugin-react-refresh": "^0.4.6",
    "jest": "^29.7.0",
    "postcss": "^8.4.38",
    "tailwindcss": "^3.4.1",
    "ts-jest": "^29.1.2",
    "typescript": "^5.2.2",
    "vite": "^5.2.0"
  }
}

vite.config.js #

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react()],
})

已尝试的解决方案 #

• 更新Ubuntu系统
• 删除node_modules和package-lock.json后重新安装依赖
• 切换不同Node.js版本（16.3.0、18.12.0、20.12.2）
• 更换不同npm版本
• 调整文件描述符限制及inotify相关配置（参考Vite官方文档）
• 删除并重新克隆整个项目

推荐解决方法 #

1. 将项目迁移到WSL原生文件系统 #

如果你的项目存放在Windows挂载目录（如/mnt/c/xxx），WSL的inotify机制无法可靠监听文件变化。建议把项目移动到WSL的原生文件系统中，比如~/projects目录下，再重新安装依赖运行。

2. 配置WSL挂载选项 #

编辑WSL的配置文件/etc/wsl.conf（如果不存在则创建），添加以下内容：

[automount]
options = "metadata,umask=0022,fmask=0133"

保存后执行wsl --shutdown关闭WSL，重新打开Ubuntu终端后再启动Vite服务。

3. 启用Vite的轮询监听模式 #

在vite.config.js中添加server.watch配置，强制使用轮询方式监听文件变化：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    watch: {
      usePolling: true,
    },
  },
})

这种方式会定期扫描文件系统，兼容性更强，适合WSL环境。

4. 关闭编辑器的"安全写入"模式 #

部分编辑器（如VS Code）默认使用"安全写入"模式，会先创建临时文件再替换原文件，导致inotify无法检测到变化。可以在编辑器设置中关闭该功能：

• VS Code：打开设置，搜索files.useExperimentalFileWatcher并设置为false，或者调整files.saveOptions相关配置。

内容的提问来源于stack exchange，提问作者Patrik Bajzík