declare module '*.css' 不够用，因为它仅声明模块存在，未提供具体类名类型，导致无智能提示且 styles.xxx 报 ts2339 错误；真正需为 *.module.css 生成精确的 record 类型声明，如通过 typed-css-modules 自动生成 .d.ts 文件或手写带引号的类名对象。
直接加 declare module '*.css' 能让 TypeScript 不再报“找不到模块”，但这是最粗糙的解法——它只消除了报错，不提供任何类名类型提示，styles.xxx 依然会提示 TS2339。
为什么 declare module '*.css' 不够用
这种全局声明把所有 .css 文件都当作导出一个空对象 {} 或泛型 Record<string string></string>，TypeScript 完全不知道你实际写了哪些类名。比如 Button.css 里有 .primary 和 .disabled，编辑器无法自动补全，styles.primary 也会被标红。
常见错误现象：
- 导入成功但无智能提示
Property 'primary' does not exist on type '{ [key: string]: string; }'- 构建正常，开发体验降级
真正需要的是 .module.css + 类名精确类型
CSS Modules 的类名是确定的、有限的，类型必须从文件内容中来，不能靠通配符猜。所以重点不是“怎么让 import 不报错”，而是“怎么让 TypeScript 知道这个 CSS 文件里到底有哪些 key”。
推荐做法：
- 只对
*.module.css（或*.module.scss）做类型声明，避免污染全局.css - 使用
typed-css-modules自动生成.d.ts文件，例如Button.module.css→Button.module.css.d.ts - 确保
tsconfig.json的include包含生成路径，如["src/**/*"] - Webpack 用户需关闭
css-loader的esModule: true（设为false），否则运行时结构与类型不一致
手动声明也能用，但仅限简单场景
如果你只有几个固定文件、不想引入额外工具，可以手写 types/css-modules.d.ts：
declare module '*.module.css' {
const classes: {
primary: string;
disabled: string;
'icon-left': string;
};
export default classes;
}
注意：
- 类名带连字符（如
icon-left）必须加引号，否则 TS 解析失败 - 每次增删类名都要同步改这里，维护成本高
- 不支持嵌套选择器或
:global()内部类名 - Vite 项目默认兼容，但 Webpack 需确认
css-loader输出格式匹配声明
真正容易被忽略的点是：生成的 .d.ts 文件名必须严格为 xxx.module.css.d.ts（不是 xxx.module.css.ts 或 xxx.css.d.ts），且 VS Code 的 TS Server 缓存常不自动更新——改完类型后务必执行 Ctrl+Shift+P → "TypeScript: Restart TS server"。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
