Vite保存文件变更后无法热更新，提示vite:hmr (ssr) [no modules matched]

我之前也碰到过一模一样的问题，折腾了好一会儿才搞明白，核心就是Vite的热更新（HMR）依赖它的模块依赖图——如果你的文件没被纳入这个依赖图，哪怕Vite检测到文件变了，也不知道要更新哪个部分。先结合你的场景给你拆解排查：

首先先明确你的项目结构和问题现象，方便对照：

你的项目结构：

demoapp/
├── public/
│   └── assets/
│       └── flags/
│           ├── de.svg
│           └── es.svg
├── src/
│   ├── app/
│   │   ├── main.ts
│   │   ├── ui.ts
│   │   ├── router.ts
│   │   ├── events.ts
│   │   └── utils.ts
│   └── styles/
│       └── index.scss
├── dist/
├── vite.config.ts
├── tsconfig.json
└── index.html

问题现象：

• 改index.html能自动刷新页面
• 改TS文件（比如ui.ts、router.ts）或者SCSS文件，完全没反应，必须手动重启dev server
• HMR日志显示vite:hmr (ssr) [no modules matched]，说明Vite找不到变更文件对应的关联模块

接下来是具体的解决步骤，按优先级来：

1. 确保所有需要热更新的文件都被纳入主依赖链 #

这是最常见的原因！Vite只会监听那些被主入口文件（或者主入口引入的文件）引用的模块。

• 对于样式文件：打开src/app/main.ts，确认里面有没有引入你的index.scss，路径要正确（从main.ts到styles的相对路径是../styles/index.scss），也就是加一行：

  import '../styles/index.scss';
  

  另外，你的_base.scss如果是被index.scss通过@import引入的，那只要index.scss被主入口引用了，_base.scss也会被纳入依赖图。
• 对于TS文件：比如ui.ts、router.ts这些，你得在main.ts里把它们import进来，比如：

  import './ui';
  import './router';
  import './events';
  import './utils';
  

  要是这些TS文件没被任何已加载的模块引用，Vite根本不知道它们和页面的关联，自然不会触发更新。

2. 检查文件路径的大小写匹配 #

尤其是在Windows系统下，系统本身不区分路径大小写，但Vite的模块依赖图是区分的。比如你在代码里写import '../Styles/index.scss'（大写S），但实际文件夹是styles（小写s），这就会导致Vite在依赖图里找不到对应的模块，出现no modules matched的提示。

3. 调整Vite配置，排除SSR干扰并显式开启HMR #

你的日志里出现了(ssr)的标记，但你并没有开启SSR配置，这可能是某个模块的引入方式意外触发了SSR模式。可以在Vite配置里显式关闭SSR相关的默认行为，同时确保HMR是开启的：

import { defineConfig } from 'vite';
export default defineConfig({
  root: '.',
  build: {
    outDir: './dist',
    emptyOutDir: true,
  },
  server: {
    port: 5173,
    open: false,
    hmr: true, // 显式开启HMR，避免默认配置被干扰
  },
  ssr: {
    noExternal: false, // 确保没有意外开启SSR相关的外部依赖处理
  },
});

4. 清除Vite缓存，重启服务 #

有时候Vite的缓存会导致依赖图异常，你可以删除node_modules/.vite这个缓存文件夹，然后重启dev server，让Vite重新生成依赖图。

按这个顺序排查下来，基本就能解决你遇到的热更新问题了——我当时就是因为漏了在main.ts里引入某个TS模块，导致改了文件完全没反应，补上引用就好了。

内容来源于stack exchange