必须为 css modules 添加类型声明才能解决 ts2307 错误；在 types/css-modules.d.ts 中声明 declare module '*.module.css' { const classes: { [key: string]: string }; export default classes; }，并确保 tsconfig.json 的 include 包含该文件。
TypeScript 本身不解析 CSS，所有引入行为都依赖构建工具（Webpack/Vite）和类型系统协同。没配好类型声明，import styles from './Button.module.css' 直接报 TS2307；没配对 loader，样式根本不会进打包流程——这两层必须同时到位。
为什么 import *.module.css 会报 TS2307？
TypeScript 编译器默认只认 .ts/.js 模块，遇到 .module.css 这类扩展名，既不解析内容，也不推断导出结构。它不是“找不到文件”，而是“根本不认识这个模块类型”。
- 错误信息如
Cannot find module './Button.module.css'或Module has no exported member 'button'，本质是类型系统“失明” - Webpack/Vite 即使已正确处理 CSS 输出，TS 在编译阶段就卡住，IDE 也无法提示
styles.button -
declare module '*.css'这种宽泛声明会破坏副作用导入（比如import 'normalize.css'），必须限定为*.module.css
如何补全 CSS Modules 的类型声明？
在项目中新建 types/css-modules.d.ts（路径可自选，但需被 tsconfig.json 的 include 覆盖），内容严格如下：
declare module '*.module.css' {
const classes: { [key: string]: string };
export default classes;
}
declare module '*.module.scss' {
const classes: { [key: string]: string };
export default classes;
}
declare module '*.module.less' {
const classes: { [key: string]: string };
export default classes;
}
-
tsconfig.json中确保"include": ["src/**/*", "types/**/*"]包含该文件 - 不要加
export =、const以外的修饰符，也不要给classes赋初始值 - 若需更严谨，可用
readonly [key: string]，但多数项目[key: string]已足够
怎么让 IDE 提示具体类名（比如 styles.container）？
上面的全局声明能过编译，但 styles.xxx 是任意字符串——要获得真实类名提示和拼写校验，得把 CSS 文件里的类名“翻译”成类型定义。
- 推荐用
css-module-types：运行npx css-module-types src/**/*.module.css，生成同名.d.ts文件 - 生成的
Button.module.css.d.ts必须和源文件在同一目录，否则 TS 找不到 - Vite 用户注意：
vite-plugin-dts默认不处理 CSS Modules，得额外配vite-plugin-css-modules-typings
非 Modules 场景下怎么引入普通 CSS？
比如 import 'normalize.css' 或 import './index.css'，这类导入只触发副作用，不导出任何值。
- 不需要类型声明，也不应加
declare module '*.css'——否则会污染全局，干扰 Modules 场景 - 确保构建工具配置了对应 loader（如 Webpack 的
css-loader+style-loader，Vite 默认支持） - 如果用的是 SCSS/Sass/Less，loader 需按顺序链式调用：
less-loader→css-loader→style-loader（Webpack） - 动态导入也适用：
await import('./theme-dark.css')，但同样需要 loader 支持，且无类型提示
最易忽略的点：类型声明文件是否真被 TS 加载了——检查 tsconfig.json 的 include 和实际文件路径是否匹配；生成的 .d.ts 是否和源 CSS 同目录；以及 declare module 是否精确限定到 *.module.* 而非宽泛通配。这三个地方错一个，styles.xxx 就永远是 any。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
