如何让NextJS检测并提示引用不存在的CSS Module类名？

方案1：开启Next.js原生CSS Module类型检查（适用TS项目，Next.js 13.1+） #

这是成本最低的方案，Next.js 13.1及以上版本内置了CSS Modules的类型自动生成能力，开启配置后就能在开发阶段直接检测到不存在的类名：

1. 在next.config.js中添加以下配置：

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    typedCssModules: true
  },
  typescript: {
    // 可选，构建时遇到TS错误直接终止，避免漏网之鱼
    ignoreBuildErrors: false,
  }
}

module.exports = nextConfig

2. 重启开发服务后，Next.js会自动为每个.module.css文件生成对应的类型定义文件，当你访问styles.I_do_not_exist这类不存在的属性时，IDE会直接飘红提示，TS编译阶段也会抛出明确错误。

如果是低于13.1版本的Next.js TS项目，可以安装typed-css-modules工具实现同等效果：

• 项目内安装依赖：npm i typed-css-modules -D
• 在package.json的scripts中添加命令："tcm": "tcm src -w"
• 开发时并行运行这个命令，会自动扫描src下所有.module.css文件生成对应的.d.ts类型文件，同样可以实现不存在类名的静态检查。

方案2：ESLint静态扫描（适用JS/TS项目） #

如果不想用类型检查，也可以用ESLint插件实现全量静态扫描：

1. 安装依赖：npm i eslint-plugin-css-modules -D
2. 在你的ESLint配置文件中添加规则：

{
  "plugins": ["css-modules"],
  "rules": {
    "css-modules/no-undef-class": "error", // 访问未定义的类直接报错误
    "css-modules/no-unused-class": "warn" // 可选，提示定义了但未使用的CSS类
  }
}

配置完成后，执行ESLint检查即可批量扫描全项目所有不存在的CSS类引用，IDE实时开发时也会同步提示。

方案3：运行时代理拦截（适用所有项目，开发阶段生效） #

如果以上静态方案都不满足需求，可以在开发环境给CSS Module的导出对象加Proxy拦截，访问不存在的属性时直接在控制台抛出警告：

// 仅开发环境生效，生产环境自动剥离不影响性能
if (process.env.NODE_ENV === 'development') {
  const styleProxy = new Proxy(styles, {
    get(target, prop) {
      if (typeof prop === 'string' && !(prop in target)) {
        console.error(`CSS类不存在：${prop}，请检查对应的CSS Module文件`)
      }
      return Reflect.get(target, prop)
    }
  })
  // 用styleProxy替换原有的styles使用即可
}

这种方案不需要修改构建配置，临时排查问题时也可以快速用上。

内容的提问来源于stack exchange，提问作者Matthieu Raynaud de Fitte