react 18 中 css 模块生效的核心是文件名必须含 .module. 后缀且大小写严格匹配，组件与样式共置，并补充 typescript 类型声明；否则样式静默失效。
React 18 项目中组织 CSS 模块，核心不是“怎么分文件夹”，而是确保每个模块化样式文件被正确识别、导入和使用——否则哪怕结构再清晰，也会出现 className="" 或样式不生效的静默失败。
文件命名必须带 .module. 后缀
CRA、Vite 和大多数现代构建工具只对匹配 /\.module\.(css|scss|less|styl)$/ 的文件启用 CSS Modules。光内容写对没用，名字错了就退化成全局样式。
-
Button.module.css✅ 会被模块化处理，import styles from './Button.module.css'返回对象 -
Button.css❌ 全局注入，styles.button是undefined，但控制台不报错 -
Button.modules.scss❌ 常见手误，多了一个s，Webpack 不识别，等同于普通 SCSS 导入 -
button.module.css与Button.module.css在 macOS/Linux 下是不同文件，大小写必须严格一致
组件与样式文件应共置，不推荐集中存放
把 components/Button/Button.jsx 和 components/Button/Button.module.css 放在同一目录下，是最小认知负担、最易维护的组织方式。
- 删除组件时，样式文件自然跟随，不会残留“幽灵 CSS”
- 重构时路径变更少，
import styles from './Button.module.css'不用反复调整相对路径 - 避免
src/styles/modules/Button.css这类集中目录：一旦多个组件共用一个类名（如container），模块化就失效了 - 如果真需复用样式逻辑，提取为
src/shared/styles/utils.module.css并明确文档说明用途，而非靠“约定”让所有人去猜
全局类与模块类混用时，字符串拼接要干净
混合使用（比如加 animate__fadeIn 动画）的关键是：模块类走 styles.xxx，全局类走纯字符串，中间用空格连接，不加引号、不加点、不嵌套模板字面量。
- ✅ 正确：
className={`${styles.root} animate__fadeIn`} - ❌ 错误：
className={`${styles.root} .animate__fadeIn`}—— 多了个.，浏览器收到的是xxx .animate__fadeIn，后半段无效 - ❌ 错误：
className={styles.root + ' animate__fadeIn'}—— 可读性差，且undefined + 'x'会变成"undefined x"，难调试 - 全局样式（如 Animate.css）务必确保已引入：在
main.jsx中import 'animate.css'，或通过 CDN 加到public/index.html；仅写类名不 import，等于白写
TypeScript 项目必须补全 SCSS/Less 类型声明
Vite 或 CRA 能把 .module.scss 编译成 JS 对象，但 TypeScript 默认不认识它，会报 TS2307: Cannot find module。
- 在项目根目录下建
src/react-app-env.d.ts（CRA）或src/env.d.ts（Vite），加入：
declare module '*.module.css' {
const classes: { [key: string]: string };
export default classes;
}
declare module '*.module.scss' {
const classes: { [key: string]: string };
export default classes;
}
- 不建议用
any类型（如const classes: any），会失去类名拼写校验 —— 写错styles.btnn就不会被 TS 提示 - 如果用了
postcss-modules-values等插件，类型声明需更精确，但 95% 的项目只需上面两段就足够
最常被忽略的其实是文件名规则和类型声明这两步——它们不报红、不崩溃，但会让样式“看起来写了却没效果”，排查起来比逻辑 bug 还费时间。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
