必须启用 typescript-plugin-css-modules 插件并配置 namedExports、camelCase 和 allowUnknownClassnames，才能实现 CSS Modules 的 TypeScript 编译期校验，否则字符串索引访问将绕过类型检查。
为什么直接写 styles['block__element--modifier'] 会绕过类型检查
TypeScript 默认无法识别字符串索引访问 CSS Modules 导出对象的合法性。即使 Button.module.css 中定义了 .btn__icon--large，styles['btn__icon--large'] 仍会被视为 string | undefined，不触发拼写错误提示。
根本原因是：TS 不知道这个字符串是否对应真实导出的类名 —— 它只把 styles 当作一个普通对象，而非带约束的映射类型。
- 编译器不会报错，但 IDE 无法补全、无法跳转
- 拼错成
'btn__icon--largs'也不会提示，直到运行时 className 生效失败 - 这种写法彻底放弃了 CSS Modules + TS 的核心价值：编译期校验
必须启用 typescript-plugin-css-modules 自动生成类型定义
仅靠 import styles from './Button.module.css' 不足以获得类型安全。需要插件在语言服务层生成 declare module '*.module.css' 声明，并将每个类名转为字面量类型。
关键配置项必须显式设置：
-
namedExports: true：启用按属性名访问（如styles.btnIconLarge），否则只有默认导出styles对象可用 -
classnameTransform: 'camelCase'：把btn__icon--large转为btnIconLarge，避免下划线/短横带来的语法问题 -
allowUnknownClassnames: false：严格模式，禁止任何未声明类名的访问（推荐）
配置后，styles.btnIconLarge 的类型是 string，而 styles.nonexistent 会立刻标红报错 Property 'nonexistent' does not exist on type '...'。
完整的Galileo AI平台 TypeScript/JS SDK 参考，用于评估、观察和保护 GenAI 应用。适用于构建 Node.js 或 TypeScript 项目。
遇到 BEM 多级嵌套类名时的命名策略
BEM 类名如 header__nav-item--active 经 camelCase 转换后变成 headerNavItemActive，可读性尚可；但若原始类名含多个短横（如 form__input-group--error--focused），转换后为 formInputGroupErrorFocused，语义易混淆。
此时建议主动控制命名粒度：
- 避免在单个类名中堆砌多层修饰，拆分为
form__input-group+form__input-group--error+form__input-group--focused - 用
asIs模式保留原始类名，改用类型断言确保安全：styles['form__input-group--error'] as string（仅限少量例外） - 在构建脚本中加一层校验：用正则扫描所有
.module.css文件，拦截不符合 BEM 规范（如含大写字母、连续短横）的类名
React 组件中使用 className 的典型陷阱
即使类型正确，运行时仍可能因组合方式出错。常见问题包括：
- 条件类名拼接：
className={`${styles.btn} ${isActive ? styles.btnActive : ''}`→ 若styles.btnActive拼错，TS 不会报错，因为整个表达式类型是string - 数组 join 写法更安全：
className={[styles.btn, isActive && styles.btnActive].filter(Boolean).join(' ')}，此时styles.btnActive单独被校验 - 第三方库如
clsx需配合类型定义：import clsx from 'clsx';+ 确保clsx的参数能被推导为string或false | undefined - 不要对
styles做Object.keys()或for...in遍历 —— 这些操作会丢失类型信息，返回string[]，完全脱离校验
最易被忽略的一点：插件生成的类型定义依赖于文件存在且被 TS 语言服务加载。如果 .module.css 文件被 gitignore 或放在 node_modules 外的非 src 目录，类型就不会生效 —— 此时一切“类型安全”都是假象。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
