Container Queries 必须作用于 BEM Block 根节点（如 .card）或其直接 wrapper，不能用于 Element（如 .card__content）；需显式声明 container-type 和 container-name，避免 display: contents 等破坏 containment 的样式，并确保容器类名在构建后仍可被 @container 匹配。
Container Queries 必须作用于 BEM Block 容器上
直接给 .card__content 加 container-type: inline-size 是无效的——Container Queries 只对具有明确尺寸上下文的容器生效，而 BEM 的 Element（如 __content）本身不构成独立布局容器。必须把 container-type 放在 Block 根节点（如 .card）或其直接包裹层（如 .card-wrapper）上。
常见错误现象：@container card (max-width: 400px) 不生效，原因是 CSS 中没定义 container-name: card，或名字拼错成 container-name: Card（大小写敏感）；更隐蔽的问题是：Block 元素本身 display: contents 或 position: absolute 会破坏 containment 上下文，导致查询失效。
- 确保 Block 根元素有明确盒模型：避免
display: contents、display: none或overflow: clip（除非你清楚它不影响 containment） - 推荐显式命名容器：
.card { container-type: inline-size; container-name: card; }，不依赖匿名容器 - 若 Block 被多层 wrapper 包裹（如
<div class="grid-item"><div class="card"></div></div>），优先把container-type放在语义最接近组件边界的 wrapper 上，而非强行塞进.card
BEM Modifier 类名要与 Container Query 状态解耦
不能用 .card--narrow 这类手动控制的修饰符去响应容器尺寸变化——它和 Container Queries 的自动响应逻辑冲突，且破坏了“样式由容器尺寸驱动”的原则。Modifier 应只表达静态、可枚举的状态（如 --loading、--error），而尺寸适配逻辑应完全交给 @container 规则。
典型翻车点：@container card (max-width: 300px) { .card--narrow { padding: 8px; } } —— 这样写看似能用，但 .card--narrow 类名在 HTML 中仍需手动添加，一旦漏加或误加，样式就断；更严重的是，它让组件行为变得不可预测：同一个 .card 在不同容器里可能因开发者疏忽而渲染出不一致的布局。
立即学习“前端免费学习笔记（深入）”；
- 所有尺寸相关样式必须写在
@container块内，且只针对 BEM Block 或其 Element，例如：@container card (max-width: 300px) { .card__title { font-size: 1rem; } } - 禁止在
@container中使用非 BEM 类名（如.mt-2）或原子类，它们无法被构建工具局部化，也违背组件封装原则 - 如果需要在 JS 中读取容器状态（比如做动画触发），用
ResizeObserver监听 Block 元素尺寸，而不是靠类名判断
SCSS 或 PostCSS 中如何安全嵌套 Container Queries
SCSS 的 & 符号容易写出非法 BEM 结构，尤其和 @container 混用时。例如：.card { @container card (max-width: 400px) { &__title { font-size: 1rem; } } } 看似简洁，但编译后生成的 CSS 选择器是 @container card (max-width: 400px) { .card__title { ... } }，这没问题；但如果写成 &__title { @container card (...) { ... } }，就违反了 Container Queries 必须作用于容器的规则，且语法错误。
真正危险的是嵌套层级错位：BEM 要求所有类名扁平，而 SCSS 嵌套容易诱导你写出 .card { &__header { &__title { ... } } }，这直接产出非法的 .card__header__title，BEM 工具链会报错，postcss-bem-linter 也会拦截。
- 只允许一级
&嵌套：即&__element和&--modifier，禁止&__element__subpart -
@container规则必须写在顶层或紧贴 Block 声明下，不要缩进到 Element 块内部 - 用 PostCSS 插件（如
postcss-container-queries）替代手写@container，它能校验容器命名是否匹配、避免重复声明
构建产物中 BEM 类名与 Container Queries 的兼容性陷阱
CSS Modules 默认生成的类名（如 Card_card__abc123）不会影响 Container Queries 生效，因为 @container 查找的是 DOM 中实际存在的 class 值，不是源码里的 .card。但问题出在开发体验和调试上：如果你在 JSX 中写 className={styles.card}，而构建后变成 class="Card_card__abc123"，那你在 DevTools 里搜 .card 就找不到对应元素，@container card 也查不到目标容器——因为 container-name: card 匹配的是类名字符串 "card"，不是哈希值。
解决方案不是禁用 CSS Modules，而是统一约定：Container Queries 所依赖的容器名，必须与 BEM Block 名一致，且该 Block 名必须出现在最终 HTML 的 class 属性中（哪怕只是作为原始名的一部分）。
- 配置 Webpack/Vite 的
localIdentName保留原始 Block 名：[name]__[local]___[hash:base64:5]，确保.card始终出现在生成类名里 - 在 JSX 中同时挂载原始名和模块化名：
className={`card ${styles.card}`}（仅用于容器节点），这样@container card能命中，样式也能局部化 - 禁止在
@container查询中使用带哈希的类名（如@container Card_card__abc123），它不具备可维护性，也无法被其他组件复用
