NextJS保存组件导入的module.css文件时触发全量重载求助

问题场景 #

在Next.js App Router环境下，修改组件目录下的*.module.css文件并保存时，会触发应用全量重载；但页面文件（如app/page.js）导入page.module.css时无此问题，组件导入普通.css文件也不会触发全量重载。即使将组件及其样式文件移至/app根目录，问题依然存在。

排查与解决方法 #

• 升级Next.js到最新稳定版
  低版本的App Router存在CSS模块热重载的已知bug，优先升级版本：

  npm install next@latest
  # 或使用yarn/pnpm
  yarn add next@latest
  pnpm add next@latest
  

• 确认组件样式导入路径
  确保组件导入.module.css时使用相对路径，避免绝对路径可能导致的热重载识别异常：

  // 正确示例
  import styles from './Component.module.css';
  

• 清理实验性配置
  若next.config.js中保留了已废弃的实验性配置（比如早期的experimental.appDir），移除这些配置：

  // next.config.js
  const nextConfig = {
    // 移除如下实验性配置（App Router现已稳定）
    // experimental: {
    //   appDir: true,
    // },
  }
  
  module.exports = nextConfig
  

• 清除缓存并重启服务
  缓存异常可能导致热重载逻辑出错，执行以下操作：

  1. 停止开发服务器
  2. 删除项目根目录下的.next文件夹和node_modules/.cache文件夹
  3. 重启开发服务器

• 测试孤立组件的热重载
  创建一个仅被单个页面引用的测试组件，导入.module.css后测试热重载是否正常，排查是否是组件多引用导致的依赖链异常。

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