因为 TypeScript 默认无法推断 CSS Modules 运行时生成的哈希类名，需通过手动或自动生成 .d.ts 声明文件（如 declare const styles: { primary: string; 'icon-left': string }; export default styles）显式定义导出键名，否则 styles.primary 无提示且类型检查失效。
为什么 import styles from './Button.module.css' 没有 TypeScript 类型提示
因为 CSS Modules 生成的类名是运行时哈希化的（如 button__primary_abc123），TypeScript 默认无法推断模块导出的字符串键。TS 看到的是一个空对象或 any，补全失效、类型检查形同虚设。
解决路径只有一条：让 TS 知道这个 CSS 文件导出哪些属性名，且每个都是 string。这需要手写或自动生成 .d.ts 声明文件。
手动声明 Button.module.css.d.ts 的最小可行写法
在对应 CSS 文件同目录下新建 Button.module.css.d.ts，内容必须严格匹配实际类名（大小写、连字符都不能错）：
declare const styles: {
primary: string;
disabled: string;
'icon-left': string;
};
export default styles;
注意点：
立即学习“前端免费学习笔记（深入）”；
-
icon-left这类含短横线的类名必须用引号包裹，否则 TS 报语法错误 - 声明中不能漏掉任何你实际在 JSX 中用到的类名，否则
styles.missingClass会报错 - 不支持通配符或正则，每个类名都得显式列出
- 如果 CSS 文件被重命名或类名变更，必须同步改
.d.ts，否则类型和运行时不一致
用 css-modules-typescript-loader 自动生成 .d.ts
手动维护很快失控，尤其组件多、类名频繁迭代时。推荐用 Webpack loader 在构建时自动提取并生成声明文件：
安装依赖：
npm install --save-dev css-modules-typescript-loader
在 webpack.config.js 的 module.rules 中添加：
{
test: /\.module\.css$/,
use: [
'style-loader',
{
loader: 'css-loader',
options: { modules: true }
},
{
loader: 'css-modules-typescript-loader',
options: { banner: '// Generated by css-modules-typescript-loader' }
}
]
}
关键行为：
- 每次构建时扫描所有
*.module.css，提取.className和:global(.selector)（后者不生成） - 生成同名
.d.ts文件，例如Button.module.css→Button.module.css.d.ts - 生成的声明默认使用
string类型，不校验类名是否真实存在（所以 CSS 里删了类但没删 JS 引用，TS 不报错） - 不支持嵌套选择器生成的复合类名（如
&:hover），只认顶层.xxx
VS Code 补全失效？检查这三个地方
即使有了 .d.ts，补全仍可能不工作：
- VS Code 没有重新加载 TS 服务：保存
.d.ts后按Ctrl+Shift+P→ “TypeScript: Restart TS server” -
tsconfig.json中"include"没覆盖*.d.ts文件，确保包含"src/**/*.d.ts" - CSS 文件名不是
*.module.css（比如写成Button.css），Webpack 和 loader 都不会触发处理逻辑，.d.ts根本不会生成
最常被忽略的是：CSS Modules 的哈希后缀（如 _abc123）永远不出现在类型声明里——.d.ts 只管“键名”，不管运行时值。补全是靠键名推导的，不是靠字符串字面量匹配。
