@layer components 是 tailwind 官方推荐的原子类组合封装方式，需置于 @tailwind base 后、utilities 前，命名加前缀且不支持伪类嵌套；适用于静态样式，动态逻辑、结构联动或主题切换应改用其他方案。
直接用 @layer components 封装原子类组合，是 Tailwind 官方认可、副作用最小、CSS 体积最可控的组件封装方式。别绕开它去写一堆 @apply 或硬塞 cn() 函数——那不是封装，是把问题从 HTML 搬到 CSS 里再藏一遍。
为什么不能在 HTML 里堆 class 或靠 cn() 拼接来“封装”
很多人以为把 px-4 py-2 bg-blue-500 rounded-lg hover:bg-blue-600 塞进 cn() 就算封装了，其实只是把混乱从模板挪到了 JS 层。这类做法会立刻暴露三个硬伤：
- 无法统一响应式断点逻辑（比如
md:px-6 lg:px-8必须手动展开，没法按尺寸条件动态合并） -
twMerge对复合变体（如group-hover:text-red-500）支持有限，容易漏掉状态联动类 - 调试时开发者工具里只看到一长串展开后的原子类，找不到原始语义名，改一个 padding 得全局搜
px-4
@layer components 的正确写法和位置约束
它不是随便丢在哪都行的 CSS 块，必须严格满足两个顺序条件：在 @tailwind base 之后、@tailwind utilities 之前。否则所有原子类优先级会错乱，hover:、group- 等变体可能失效。
命名要加前缀（如 .card-default），避免和未来 Tailwind 版本新增的原生 class 冲突。不支持伪类嵌套写法（&:hover），必须用 @apply 配合变体语法：
@layer components {
.btn-primary {
@apply bg-blue-500 text-white px-4 py-2 rounded-lg font-medium shadow transition-colors;
@apply hover:bg-blue-600 focus:outline-none focus:ring-2 focus:ring-blue-400;
}
}
注意：@apply 后面不能跟带空格的复合类（如 md:hover:bg-red-500），这种必须拆成独立规则或放弃。
什么时候该放弃 @layer components，转用其他方式
它只适合静态样式契约明确的 UI 元素。一旦出现以下任一情况，就该收手，改用更灵活的方案：
- 需要根据 props 动态切换尺寸/颜色/变体组合（如
size="sm"+variant="outline"+disabled）——此时 HTML 中用class="btn btn-sm btn-outline disabled:opacity-50"更可靠 - 依赖
group/peer实现多元素联动（如下拉菜单展开态影响箭头旋转）——@layer无法表达结构关系，得靠 HTML 结构 + 原子类显式控制 - 主题切换涉及大量变量映射（如暗色模式下所有
bg-gray-100要变成bg-gray-800）——这时该用 CSS 自定义属性 +prefers-color-scheme，而不是在@layer里写两套重复规则
真正难的不是怎么写 @layer components，而是判断哪些东西**不该封装**。Tailwind 的原子性不是缺陷，是约束——它逼你把“什么该变、什么不该变”想清楚。一旦开始为兼容性妥协而加 wrapper div、为动态逻辑硬塞 @apply，你就已经在背离它的设计初衷了。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
