TypeScript找不到本地CSS module模块报错如何解决

问题场景 #

将React应用重构为TypeScript版本时，组件内引入CSS模块文件TypeScript会抛出如下错误：

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

该报错本质是TypeScript默认无法识别.module.css这类非脚本文件的导出类型，完全不需要依赖Webpack即可修复，通用操作步骤如下：

解决步骤 #

1. 新增CSS模块类型声明文件 #

在项目源码目录（即tsconfig.json中include配置覆盖到的路径，通常为src/目录下），新建命名为css-modules.d.ts的类型声明文件，写入以下内容：

// 适配原生CSS模块
declare module '*.module.css' {
  const classes: { readonly [key: string]: string };
  export default classes;
}

// 项目如果使用Less/Sass等CSS预处理器，同步添加对应声明即可
declare module '*.module.less' {
  const classes: { readonly [key: string]: string };
  export default classes;
}
declare module '*.module.scss' {
  const classes: { readonly [key: string]: string };
  export default classes;
}

这段声明的作用是告知TypeScript：所有后缀匹配.module.css的文件，默认导出一个只读对象，对象的键值均为字符串类型，和CSS模块实际导出的「原始类名-编译后哈希类名」映射规则完全一致。

2. 校验tsconfig配置 #

打开项目根目录的tsconfig.json，确认以下配置正确，保证TS能正常加载刚编写的声明文件：

• include数组需覆盖声明文件所在路径，比如声明文件放在src/下时，要保证include包含"src/**/*"
• 若自定义了compilerOptions.typeRoots配置，需要将全局类型文件所在目录加入配置；未自定义该配置时保持默认即可，TS会自动扫描源码内的.d.ts文件和node_modules/@types下的类型包
• 不要开启compilerOptions.noResolve配置，该配置会阻止TS自动加载类型声明文件

3. 特定构建工具简化方案 #

如果使用Vite、Rsbuild这类无Webpack的现代构建工具，不需要手动编写上述声明文件，只要在tsconfig.json的compilerOptions.types数组中加入对应构建工具的客户端类型即可，比如Vite项目直接添加"vite/client"，该类型包内置了CSS模块、静态资源等所有前端常用文件的类型声明。

4. 清除TS缓存 #

如果配置完成后报错仍然存在，重启TS服务即可：在VS Code中按下快捷键Ctrl+Shift+P（Mac系统为Cmd+Shift+P），调出命令面板后输入Restart TS Server，回车执行后等待TS重新加载项目，报错就会消失。

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