React Vite项目CSS模块报错：无法找到模块或对应类型声明

在React+Vite+TypeScript项目中，导入同目录下的NavbarSample.module.css时出现以下报错，且项目内所有CSS模块文件均存在此问题：

Cannot find module './NavbarSample.module.css' or its corresponding type declarations.

相关代码与配置 #

NavbarSample.module.css内容

.navbar {
  width: rem(80px);
  height: rem(750px);
  padding: var(--mantine-spacing-md);
  display: flex;
  flex-direction: column;
  border-right: rem(1px) solid
    light-dark(var(--mantine-color-gray-3), var(--mantine-color-dark-4));
}

.tsx文件中的导入代码

import classes from './NavbarSample.module.css';

vite.config.ts配置

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import fs from 'fs';
import path from "path";

export default defineConfig({
    plugins: [react()],
    server: {
        port: 8080
    },
    resolve: {
        alias: {
            "@assets":path.resolve(__dirname, "./assets") ,
            "@service":path.resolve(__dirname, "./services") ,
        },
      },
});

pnpm依赖列表

dependencies:
@emotion/react 11.11.1                 @tabler/icons-react 2.34.0             mantine-react-table 1.3.3
@mantine/core 6.0.20                   @tanstack/react-query 4.35.3           react 18.2.0
@mantine/dates 6.0.20                  @tanstack/react-query-devtools 4.35.3  react-axios 2.0.6
@mantine/form 6.0.20                   @tanstack/react-table 8.9.9            react-chartjs-2 5.2.0
@mantine/hooks 6.0.20                  axios 1.5.0                            react-dom 18.2.0
@mantine/modals 6.0.20                 chart.js 4.4.0                         react-router-dom 6.16.0
@mantine/notifications 6.0.20          cronstrue 2.32.0                       react-table 7.8.0
@mui/material 5.14.11                  dayjs 1.11.9                           recharts 2.8.0

devDependencies:
@types/node 20.6.0                       eslint 8.40.0                            eslint-plugin-react-refresh 0.4.3
@types/react 18.2.21                     eslint-config-prettier 8.8.0             prettier 2.8.8
@types/react-dom 18.2.7                  eslint-plugin-jest 27.2.1                typescript 5.0.4
@typescript-eslint/eslint-plugin 5.59.6  eslint-plugin-prettier 4.2.1             vite 4.4.9
@typescript-eslint/parser 5.59.6         eslint-plugin-react 7.32.2
@vitejs/plugin-react 4.0.4               eslint-plugin-react-hooks 4.6.0

解决方案 #

该问题源于TypeScript无法识别CSS模块的类型声明，按以下步骤修复：

1. 添加CSS模块类型声明
   在项目src目录下新建或编辑vite-env.d.ts文件，加入以下内容：

/// <reference types="vite/client" />

declare module '*.module.css' {
  const classes: { [key: string]: string };
  export default classes;
}

// 若使用SCSS模块，可追加以下声明
declare module '*.module.scss' {
  const classes: { [key: string]: string };
  export default classes;
}

2. 检查tsconfig.json配置
   确保tsconfig.json的include字段包含上述类型声明文件，同时确认模块解析配置正确：

{
  "compilerOptions": {
    "moduleResolution": "bundler"
  },
  "include": ["src/**/*", "src/vite-env.d.ts"]
}

3. 重启TypeScript服务
   在VSCode中按下Ctrl+Shift+P（Windows）或Cmd+Shift+P（Mac），输入TypeScript: Restart TS Server，重启后报错即可消失。

4. 验证Vite插件配置
   @vitejs/plugin-react默认支持CSS模块，只需确保CSS文件名严格遵循*.module.css命名规范即可。

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