typescript 默认不识别 css modules 类型，需手动声明 declare module '*.module.css' 提供 { [key: string]: string } 类型，否则 import styles 无类型提示；精确类名提示需手写 .d.ts 或依赖 ai 插件辅助推导。
不能自动生成，必须手动声明或通过类型文件统一覆盖。 TypeScript 本身不解析 CSS 文件内容，也不读取构建工具（如 Vite 或 Webpack）生成的类名映射，所以不存在“自动推导 .module.css 中有哪些类名并生成 interface”的可靠机制。所谓“自动生成”，实际是靠开发者主动触发的辅助行为（如 AI 插件 infer），或靠约定式声明兜底。
为什么 import styles from './Button.module.css' 不报错但没类型提示
默认情况下，TypeScript 把 ./Button.module.css 当作一个无类型模块，返回 any —— 所以能编译通过，但编辑器无法提示 styles.primary 或校验拼写。根本原因是：TS 没见过这个模块的结构，也没人告诉它这个模块导出的是 { [key: string]: string }。
- 错误现象：
ts(2307) Cannot find module './Button.module.css'或有导入但styles.xxx无补全、无报错 - 本质原因：缺少模块声明（
declare module '*.module.css'），TS 不知道该模块长什么样 - 影响范围：所有
.module.css、.module.scss、.module.less等后缀的 CSS Modules 文件
最稳妥的声明方式：全局 types/css-modules.d.ts
在项目 src/types/ 或根目录 types/ 下新建 css-modules.d.ts，内容如下：
使用 @ainative/react-sdk 为 React 应用添加 AI 聊天和积分。适用于 (1) 安装 @ainative/react-sdk，(2) 使用 useChat hook 实现聊天完成。
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.sass' {
const classes: { [key: string]: string };
export default classes;
}
- 必须放在 TS 能扫描到的路径中（检查
tsconfig.json的include或typeRoots） - 如果用 Vite，确保
tsconfig.json包含该文件，例如："include": ["src/**/*", "types/**/*"] - 不需要为每个 CSS 文件单独写
.d.ts，一份声明全局生效 - 缺点：只保证类型安全（不会拼错字段名），但不提供具体类名列表（比如
primary、disabled仍需靠记忆或查源码）
想让编辑器提示具体类名？得靠人工对齐或 AI 辅助
如果你希望 styles. 后能直接看到 primary、container 这些真实类名，就得放弃“泛型对象”声明，改用精确的 interface。但这个过程无法全自动：
- 方法一（推荐）：在 CSS 文件同目录下建
Button.module.css.d.ts，手写对应类名 —— 类名变更时必须同步维护，否则类型失效 - 方法二（半自动）：用 CodeGeex 或类似插件，在 CSS 文件保存后执行「Infer Interface from CSS」（注意：这不是标准功能，依赖插件实现；且仅当插件能解析 CSS AST 时才可能提取类名）
- 关键限制：插件无法感知
@apply、@import或 CSS-in-JS 注入的类，也无法处理动态拼接类名（如styles[`item-${size}`]）
真正容易被忽略的点是：很多人以为加了 declare module '*.module.css' 就万事大吉，结果发现 styles.nonexistent 居然不报错。这是因为声明里用了 [key: string] —— 它允许任意字符串索引。要严格约束，只能放弃泛型，走逐文件 .d.ts 声明，或者用构建时生成工具（如 typed-css-modules），但后者已多年未维护，与现代 Vite/ESBuild 兼容性差。实际项目中，95% 的团队选的是“全局泛型声明 + 编辑器搜索 CSS 文件查类名”组合。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
