TypeScript 中 CSS 类名类型提示需借助工具链生成类型定义：CSS Modules 用 typed-css-modules 或 css-module-types，Tailwind 用 tailwindcss-typegen，全局 CSS 需手动声明或原子化方案；类名连字符自动转驼峰但类型保留原始字符串；关键在 .d.ts 文件生成、路径匹配及 PostCSS 兼容性。
如何让 CSS 类名在 TypeScript 中获得类型提示
直接给 CSS 类名加类型，TypeScript 本身不支持；必须借助工具链生成类型定义。核心是把 css 或 scss 文件里的类名“翻译”成 TS 接口或字符串字面量类型。
最常用且轻量的方案是 typed-css-modules（适用于 CSS Modules）或 css-module-types（更现代，支持 declare module 方式）。如果你用的是 tailwind.css 或全局 CSS，就得靠 csstype + 手动声明，或者用 unocss 这类原子化方案自带的类型生成能力。
- 只对
.module.css文件生效，普通.css不会生成类型 - 生成的
foo.module.css.d.ts必须和源文件同目录，否则import styles from './foo.module.css'无法推导类型 - 类名含连字符（如
btn-primary）会被自动转为驼峰（btnPrimary），但类型里仍保留原始字符串字面量
为什么 import styles from './Button.module.css' 有时没类型、有时报错
根本原因不是 TypeScript 配置问题，而是模块解析路径和声明文件缺失。TS 默认不认识 .css 后缀，必须靠 declare module '*.module.css' 告诉它“这类文件导出一个对象”，再靠生成的 .d.ts 补充具体键名。
常见错误现象：Property 'container' does not exist on type '{} —— 这说明 Button.module.css.d.ts 没生成，或生成了但内容为空（比如 CSS 文件里根本没写 .container）。
立即学习“前端免费学习笔记（深入）”；
- 检查构建脚本是否真执行了类型生成命令（例如
npx tcm src/**/*.module.css） - 确认
tsconfig.json的include包含了.d.ts文件路径 - 如果用了 Vite，插件
vite-plugin-dts默认不处理 CSS Modules，得额外配vite-plugin-css-modules-typings
clsx 和 twMerge 在类型安全下的表现差异
clsx 本身不提供类型保护，它只是拼字符串；传入非定义类名也不会报错。而 twMerge 结合 tailwind-merge 的 createContext 可以做运行时合并校验，但类型层面仍依赖 tailwind.config.ts + tailwindcss-typegen 生成的 twMerge 类型。
关键区别：用 clsx 时，styles.btnPrimary 是类型安全的，但 clsx('btn-primary', styles.container) 中的 'btn-primary' 不受控；而 twMerge 配合类型生成后，能对 twMerge('p-2', 'text-red-500') 做合法值校验。
-
clsx更适合已有 CSS Modules 项目，轻量无侵入 -
twMerge类型需配合tailwindcss-typegen插件，且要求tailwind.config.ts导出可被读取的配置对象 - 二者都不解决“动态拼接类名”的类型问题（如
clsx(`${prefix}-icon`)），这种必须用satisfies string或自定义类型守卫
PostCSS 插件与类型生成的兼容性陷阱
很多团队用 postcss-prefixwrap 或 postcss-nested 处理样式作用域或嵌套，但这些插件会在构建时改写类名——而类型生成工具通常只读原始文件，导致 .d.ts 里的类名和最终生成的 CSS 不一致。
典型表现：代码里写了 styles['header-title']，TS 不报错，但浏览器里找不到对应样式。因为 PostCSS 把它编译成了 MyComponent_header-title__abc123，而类型文件里还是 header-title。
- 解决方案只有两种：要么关掉影响类名的 PostCSS 插件（推荐用于开发期类型生成）
- 要么用支持 PostCSS 解析的工具，例如
css-modules-typescript-loader（Webpack）或vite-plugin-css-modules-typings的postcss选项 - 注意
css-loader的localsConvention配置（如camelCaseOnly）也会影响类型中的属性名形式
真正难搞的不是怎么生成类型，而是确保生成时机、构建流程、开发服务器三者看到的类名完全一致。稍有错位，类型就变成“看起来安全，实际失效”的幻觉。
