CSS Modules 通过编译时重命名类名实现样式局部作用域，需文件名含 .module.css、构建工具支持（如 Webpack 配 modules: true），导入后通过对象访问类名，不支持全局嵌套，伪元素和动画需 :local() 包裹。
如何用 CSS Modules 实现页面局部样式
CSS Modules 是目前最主流的局部样式方案，它通过编译时重命名类名，让样式天然具备作用域隔离。关键不是“怎么写 CSS”，而是“怎么让构建工具处理它”。
使用前确认你的项目已配置支持 CSS Modules 的 loader（如 Webpack 的 css-loader 开启 modules: true）；Vite 和 Next.js 默认已支持，但需文件名带 .module.css 后缀。
- 文件必须命名为
Button.module.css（不能是Button.css），否则不会启用模块化 - 在 JS 中导入时，得到的是一个对象：
import styles from './Button.module.css'，类名需通过styles.primary访问 - 不支持全局选择器嵌套（如
:global(.icon) { ... }需显式声明，且仅用于穿透场景 - 动态类名要拼接正确：
className={`${styles.btn} ${props.disabled ? styles.disabled : ''}`，空字符串会生成多余空格，建议用clsx库
为什么不能直接用 scoped（Vue）或 :host（Shadow DOM）
这些方案依赖特定框架或浏览器能力，不具备通用性。比如 Vue 的 <style scoped></style> 本质是属性选择器模拟（data-v-f3f3eg9），仍可能被更高权重的选择器覆盖；Shadow DOM 则面临 SSR 不友好、调试困难、CSS 变量透传复杂等问题。
纯 CSS Modules 不依赖运行时，零额外包体积，且与 React/Vue/Svelte 兼容。真正限制它的只有构建链路——如果你用原生 HTML + esbuild，它就不可用。
立即学习“前端免费学习笔记（深入）”；
- Webpack 用户：确保
css-loader版本 ≥ 5，并配置modules: { mode: 'local' } - Vite 用户：默认识别
.module.css，但import './index.module.css'不会自动注入，仍需在组件中显式使用生成的类名 - 注意
composes语法已被废弃，改用@layer或 JS 层组合
createUseStyles（JSS）和 styled-components 的适用边界
这类 CSS-in-JS 方案也能实现局部作用域，但引入了运行时开销和序列化成本。它们更适合需要动态主题、条件样式或服务端渲染中 CSS 提取逻辑复杂的场景。
如果只是想避免样式污染，又不想增加 bundle size，优先选 CSS Modules；如果组件需要大量基于 props 的内联计算（如 width: ${p => p.w}px），再考虑 CSS-in-JS。
-
styled-components在生产环境需启用BABEL_ENV=production才压缩 class 名 - JSS 的
createUseStyles要求 hook 必须在函数组件顶层调用，不支持条件调用 - 所有 CSS-in-JS 方案都会让开发者失去对原生 CSS 工具链（如 PostCSS 插件、CSS Lint）的部分控制力
容易被忽略的继承与重置问题
局部样式只解决类名冲突，不解决 CSS 继承链污染。例如父组件设置了 font-family: 'PingFang SC'，子组件即使用了 CSS Modules，文字仍会继承——这跟作用域无关，是 CSS 天然行为。
常见对策是结合 all: unset 或重置基础样式，但更稳妥的做法是在设计系统层统一约束根节点的继承属性。
- 不要在局部样式里写
html、body或* {}，它们永远是全局的 - 伪元素（
::before）、动画名称（@keyframes）默认仍是全局，需用:local()包裹（如@keyframes :local(slideIn)） - 媒体查询中的类名无需额外处理，CSS Modules 会一并重命名
