如何在Vite（React+TypeScript）项目中为CSS Modules添加类型

1. 启用Vite内置的CSS Modules类型生成 #

Vite原生支持自动生成CSS Modules的类型声明，无需额外插件即可实现类名类型提示。先检查vite.config.ts的配置：

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

export default defineConfig({
  plugins: [react()],
  css: {
    modules: {
      // 可选：自定义类名生成规则，保持和项目一致即可
      generateScopedName: '[name]__[local]___[hash:base64:5]',
      // 开启自动生成类型声明文件
      declaration: true,
      // 可选：指定类型文件输出目录，方便管理
      declarationDir: './src/types/css-modules'
    }
  }
})

接着在tsconfig.json中添加类型文件的扫描路径，确保TypeScript能识别自动生成的.d.ts文件：

{
  "compilerOptions": {
    "typeRoots": ["./src/types", "./node_modules/@types"],
    "types": ["vite/client"]
  },
  "include": ["src/**/*", "src/types/**/*"]
}

2. 修正typescript-plugin-css-modules的配置（若坚持使用该插件） #

如果之前配置未生效，大概率是插件启用方式有误：

• 先安装依赖：npm install typescript-plugin-css-modules --save-dev
• 在tsconfig.json中正确配置插件：

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "typescript-plugin-css-modules",
        "options": {
          // 匹配你的CSS Modules文件后缀，比如.module.css
          "customMatcher": "\\.module\\.css$"
        }
      }
    ]
  }
}

• 针对VSCode，需确保使用工作区的TypeScript版本：打开设置，添加

{
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}

之后重启VSCode，让TypeScript语言服务重新加载配置。

3. 检查导入方式的正确性 #

CSS Modules导出的是一个对象，而非单独的类名成员，错误的导入方式会直接导致类型报错：

• 正确的默认导入方式（推荐）：

import styles from './test.module.css';

// 使用时：<div className={styles.testCssClass}></div>

• 类型+命名导入方式（需插件支持）：

import type { CSSModuleClasses } from './test.module.css';
import * as styles from './test.module.css';

// 使用时：<div className={styles.testCssClass}></div>

不要用import { testCssClass } from './test.module.css'这种命名导入，不符合CSS Modules的导出规范。

4. 清除缓存并重启服务 #

• 删除node_modules/.vite目录，清除Vite缓存
• 重启Vite开发服务器：npm run dev
• 重启编辑器（如VSCode），让TypeScript重新加载所有类型文件

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