用途:指导在自定义 CSS 中通过 @apply 复用 Tailwind 工具类声明,用 @layer 将自定义 CSS 归入 base、components、utilities 层,并在 v4 的 scoped style 块中用 @reference 让设计令牌可见。
主要能力:@apply 把工具类声明复制进普通 CSS 选择器,必须写在选择器内,不能置于顶层;@layer 决定层叠顺序 base < components < utilities;@reference(仅 v4)用于 Vue、Svelte、CSS Modules 的 scoped 块,使用 @apply 或 @variant 时必须是首行,否则报 Cannot apply unknown utility class。
使用方式:组件类放入 @layer components,元素默认样式放入 @layer base,单一用途辅助类放入 @layer utilities。v3 的 !important 写法为 @apply font-bold !important;,HTML 中为 !font-bold;v4 为 @apply font-bold!;,HTML 中为 font-bold!,两版语法不可混用。
适用场景:纯 HTML、MDX、CMS 模板中的共享类名,以及覆盖第三方库(如 react-select、Algolia DocSearch)的样式。在 React、Vue、Svelte 等组件框架中应优先抽取组件而非使用 @apply。
限制:@apply 规则不应放在 @layer 之外,否则会排在工具层之后失去覆盖能力;不要为单个工具类使用 @apply;v4 scoped 样式缺少 @reference 会报错。v3 中报错通常因类未被扫描、拼写错误或主题未注册。插件注入的 utilities/components 会进入对应层,覆盖异常时需在 DevTools 中核对最终顺序。