TypeScript 默认不识别 .module.css 文件，需通过声明模块解决 TS2307 错误；最简方案是全局通配声明 declare module '*.module.css'，精准方案为每个 CSS 文件配同名 .d.ts，推荐使用 typescript-plugin-css-modules 插件实现自动类型推导与智能补全。
TypeScript 默认不认 .module.css 文件，直接 import styles from './Button.module.css' 必报 TS2307 错误——不是你写错了，是 TS 缺少“户口本”。必须补类型声明，否则编译过不去。
为什么 import 会报 TS2307？
TypeScript 只解析 .ts/.d.ts/.js，遇到 .module.css 就当黑盒，不知道它导出什么结构。构建工具（Vite/Webpack）确实把 CSS 编译成对象，但 TS 不知道这个对象长什么样，所以拦着不让你用。
- 典型错误信息：
Cannot find module './Button.module.css' or its corresponding type declarations - 路径大小写不一致（文件叫
button.module.css，却写成Button.module.css） -
tsconfig.json的include没覆盖到声明文件路径 - VS Code 的 TS Server 缓存没刷新，改了声明也不生效
最简方案：全局通配声明（适合快速启动）
在项目根目录或 src/ 下新建 globals.d.ts（后缀必须是 .d.ts），内容只写一行：
declare module '*.module.css';
如果还要支持 SCSS/Sass/Less，再加对应行：
Galileo TypeScript sdk
下载
完整的Galileo AI平台 TypeScript/JS SDK 参考，用于评估、观察和保护 GenAI 应用。适用于构建 Node.js 或 TypeScript 项目。
立即学习“前端免费学习笔记（深入）”；
declare module '*.module.scss';<br>declare module '*.module.sass';<br>declare module '*.module.less';
- 确保
tsconfig.json的include包含该文件，例如："include": ["src/**/*", "globals.d.ts"] - 别用
globals.ts—— TS 不会把它当类型声明处理 - 这个方案能过编译，但
styles.xxx不会自动补全类名
精准方案：为每个 CSS 文件配 .d.ts（支持类名提示）
想让 styles.primary 有补全、拼写校验和跳转，就得给每个 .module.css 文件写同名 .d.ts：
declare module './Button.module.css' {<br> const classes: {<br> primary: string;<br> disabled: string;<br> 'icon-left': string; // 连字符类名必须加引号<br> };<br> export default classes;<br>}
- 文件名必须严格匹配：
Button.module.css.d.ts，不能是Button.module.css.ts或Button.css.d.ts - 每次增删 CSS 类，都得手动同步改这里，维护成本高
- Vite 默认能生成这类声明；Webpack 需确认
css-loader输出格式是否匹配（比如开启exportLocalsConvention: 'camelCaseOnly'）
推荐方案：typescript-plugin-css-modules（兼顾智能与省力）
装插件自动补全 + 类型检查，不用手写一堆 .d.ts：
npm install -D typescript-plugin-css-modules- 在
tsconfig.json中加插件配置："plugins": [{ "name": "typescript-plugin-css-modules" }] - 配合一个基础声明文件（如
src/custom.d.ts）：declare module '*.module.css' { const classes: { [key: string]: string }; export default classes; } - 插件会自动扫描 CSS 文件，生成实时类型，支持跳转、补全、拼写校验
- 注意：VS Code 要设为使用“工作区版本”的 TypeScript，否则插件不生效
真正麻烦的不是声明本身，而是声明文件被 TS 加载的路径和时机——include 漏掉、缓存没清、后缀写错，都会让声明形同虚设。动手前先确认 tsconfig.json 是否真读到了那个 .d.ts 文件。
