CSS Module中@media易失控，因媒体查询全局生效且断点值难复用；应统一用:root变量定义断点，媒体查询内使用var()，配合composes复用响应式类，并严格统一min-width策略及viewport标签。
为什么直接在CSS Module里写@media容易失控
CSS Module 默认为每个类名生成唯一哈希，但 @media 规则本身不参与局部作用域隔离——它始终是全局生效的。你写 .container { width: 100%; } @media (min-width: 768px) { .container { width: 750px; } }，看似没问题，但一旦多个组件都定义了同名类（比如都叫 card），它们的媒体查询会互相覆盖或叠加，最终样式行为不可预测。
更麻烦的是：CSS Module 不支持跨文件复用断点值。你在 Header.module.css 里写 min-width: 768px，在 Grid.module.css 里又写一遍 min-width: 768px，后期想统一改成 769px，就得全局搜索替换，漏一个就出问题。
用 :root + CSS 变量统一断点，但别在媒体查询条件里用
CSS 变量不能出现在 @media 条件中，@media (min-width: var(--breakpoint-md)) 是无效语法，浏览器直接忽略整条规则。但你可以把变量用在媒体查询「内部」的声明块里，实现逻辑解耦。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 在全局 CSS（如
index.css或:root所在文件）中定义断点变量：:root { --breakpoint-sm: 480px; --breakpoint-md: 768px; --breakpoint-lg: 1024px; } - 在 CSS Module 中只写媒体查询条件一次，内部用
var()控制多个属性：@media (min-width: 768px) { :root { --font-size-base: 1.125rem; --gap: 1.5rem; } } - 确保所有用到这些变量的组件类都显式引用：
.title { font-size: var(--font-size-base); margin-bottom: var(--gap); } - 避免在局部选择器里重定义断点变量，比如
.card { --breakpoint-md: 900px; }—— 这不会影响@media查询范围，只会污染自身作用域
配合 composes 复用响应式行为，而不是重复写 @media
CSS Module 的 composes 不仅能合并类，还能跨文件组合媒体查询逻辑。比如你有一个 responsive.module.css 专门管理断点样式：
.sm-only {
display: block;
}
@media (min-width: 480px) {
.sm-only {
display: none;
}
}
.md-up {
display: none;
}
@media (min-width: 768px) {
.md-up {
display: block;
}
}
然后在业务组件中直接复用：
.header {
composes: md-up from './responsive.module.css';
padding: 1rem;
}
.navItem {
composes: sm-only from './responsive.module.css';
font-size: 0.875rem;
}
这样既避免重复写 @media，又让响应式意图清晰可读。注意：composes 只在构建时解析，不会增加运行时开销。
别用 max-width 和 min-width 混搭，尤其在模块间协作时
一个模块用 @media (max-width: 767px)，另一个用 @media (min-width: 768px)，表面看无缝衔接，实际存在 1px 空隙（比如 767.5px 视口）。更严重的是，CSS Module 编译后类名哈希不同，两个媒体查询可能被拆到不同 style 标签里，加载顺序不确定，导致样式竞态。
统一策略比“看起来差不多”重要得多：
- 全项目只用
min-width，从移动优先向上增强 - 断点数值必须严格对齐：如果定义了
--breakpoint-md: 768px，所有@media都用768px，不要出现767px或768.01px - 类名中的断点标识要和数值一致，比如
hidden-md对应@media (min-width: 768px)，不是hidden-sm却匹配768px - 禁用
min-device-width、max-device-width—— 它们依赖物理像素，在缩放、分屏、DevTools 模拟下完全不可靠
最易被忽略的一点：viewport meta 标签没加，@media 在真机上基本等于摆设。哪怕 CSS Module 写得再优雅，<meta name="viewport" content="width=device-width, initial-scale=1"> 漏掉，所有断点都会失效。
