TS2307错误源于TypeScript默认不识别.module.css文件，需通过declare module '*.module.css'声明或为每个CSS Module手写.d.ts文件实现类型支持，但前者无补全，后者需同步维护类名。
为什么 import './Button.module.css' 会报 TS2307？
TypeScript 编译器默认只识别 .ts、.js、.d.ts 文件，遇到 .module.css 就直接判定为“未知模块”，不是构建工具没生效，而是 TS 在类型检查阶段就卡住了。错误信息典型是：Cannot find module './Button.module.css' or its corresponding type declarations。
常见诱因包括：
- 路径大小写不一致（文件叫
button.module.css，但 import 写成Button.module.css） -
globals.d.ts或其他声明文件未被tsconfig.json的include覆盖 - VS Code 的 TypeScript Server 缓存未刷新，改了声明也不生效
declare module '*.module.css' 是最简解法，但有明显局限
在项目根目录或 src/ 下新建 globals.d.ts，内容仅一行：
declare module '*.module.css';
这能消除 TS2307，但带来两个硬伤：
立即学习“前端免费学习笔记（深入）”；
- 编辑器对
styles.primary无自动补全，类名拼错也无提示 - 如果误写了不存在的类名（比如
styles.primry），TS 不会报TS2339 - 不支持
.module.scss，需额外加declare module '*.module.scss';
务必确认 tsconfig.json 中 include 包含该文件，例如："include": ["src/**/*", "globals.d.ts"]；不能用 .ts 后缀，否则 TS 完全忽略。
要类名补全，必须为每个 CSS Module 手写或生成 .d.ts
想让 styles.iconLeft 和 styles['icon-left'] 都有类型提示，就得精确声明类名结构。例如 Button.module.css 对应的 Button.module.css.d.ts：
declare module '*.module.css' {
const classes: {
primary: string;
disabled: string;
'icon-left': string; // 连字符类名必须加引号
};
export default classes;
}
关键约束：
- 文件名必须严格为
xxx.module.css.d.ts，不是xxx.module.css.ts或xxx.css.d.ts - 每次增删 CSS 类，都得同步改这个文件，维护成本高
- Vite 默认支持自动生成这类声明；Webpack 用户需确保
css-loader输出格式匹配（esModule: false可能更稳）
别声明 *.css，只声明 *.module.css
全局 declare module '*.css' 看似省事，实际容易踩坑：
- 它会让所有
import 'bootstrap/dist/css/bootstrap.min.css'这类副作用导入也必须接收默认导出，导致编译失败 - CSS Modules 的类名是确定的，而普通 CSS 导入通常无导出，类型声明与运行时行为错位
- 真正该声明的是明确启用模块化的后缀：只用
*.module.css和*.module.scss
真正容易被忽略的点是：VS Code 的 TS Server 缓存极难自动感知 .d.ts 变更——哪怕你手写完、保存了、重开了编辑器，仍可能不生效。必须手动执行 Ctrl+Shift+P → TypeScript: Restart TS server。
