跳到正文

我所理解的 UnoCSS 最佳实践(3):语义类名与工具类的工程实践

我所理解的 UnoCSS 最佳实践

  1. 为什么选择 UnoCSS
  2. CSS 如何减少重复
  3. 语义类名与工具类的工程实践(当前)
  4. Tailwind CSS 与 UnoCSS 的兼容边界
  5. Wind3 与 Wind4 的区别与迁移
  6. 工具类、任意值与任意属性怎么选
  7. 利用 Lint 规范写法

模板保留元素职责,样式层组织视觉细节,组件接口管理尺寸、状态和行为。这套分工可以用在 UnoCSS 项目,也可以用在已有 Tailwind 项目;采用哪种声明语法,要继续服从当前工具与版本。

本文以「语义类名 + 局部样式 + apply」作为主要写法。UnoCSS 示例沿用 Vue / SCSS 链路,相关段落明确使用其单位简写、变量简写与分组;Tailwind v4 示例使用普通 CSS,已有 v3 项目保留自己的预处理配置。选择工具的理由见《为什么选择 UnoCSS》,这里讨论怎样在维护代码时逐步应用这些方法。

先让模板表达职责

<template>
  <article class="resource-card" :class="{ 'resource-card--is-saved': saved }">
    <a class="resource-card__title" :href="href">{{ title }}</a>
    <p class="resource-card__summary">{{ summary }}</p>
    <div class="resource-card__actions"><slot name="actions" /></div>
  </article>
</template>

标题、摘要、操作区和收藏状态都能从模板里找到。间距、字体、断点和交互色放在局部样式中,检查布局时再展开。CSS Modules 已经提供类名隔离时,Block 前缀可以按项目约定简化,元素职责和状态仍然值得表达清楚。

直接组合工具类与语义类加 apply 的源码组织对照

这项选择优化的是阅读路径。直接工具类便于观察一个节点的视觉实现;我更常从结构与行为读起,因此选择语义类名加 apply。需要长期给扩展或外部样式使用的 class,还应明确稳定性与兼容约束;普通内部类名不会自动成为公共 API。

apply 生成样式,DOM 标记继续留在 DOM

apply 将当前工具能识别的 utility 展开到选择器里。它不会给元素添加 class,也不会把普通 CSS 值自动识别成 utility。先确认 token 能生成什么,再决定它适不适合放进 apply。

属性值与 utility 分开判断

.tab {
  transition-timing-function: ease;
}

这里的 ease 是原生 CSS 值。Tailwind v3 / v4 默认没有裸 ease utility,需要保持这条曲线时可以写 @apply ease-[ease]。UnoCSS Wind3 / Wind4 接受裸 ease,但默认曲线也不能直接当成原生 ease。

因此,通用规则是根据实际配置判断输入,不能将一套工具的黑名单原样用于另一套。任意值推断和同名语义差异,见兼容边界篇。

group 与 peer 依赖真实元素

<button class="card group">
  <span class="card__text group-hover:text-white">内容</span>
</button>

group 是祖先状态的 DOM 标记,peer 标记供后面的兄弟节点引用。两者都不能靠 @apply group、@apply peer 添加到元素上。完整的 group-hover:text-white 则包含状态与 utility,生成选择器后仍会查找真实 DOM 标记。

模板已经使用这套关系时,保留 marker。希望模板只写职责类名时,可以直接表达相同的状态关系:

.card:hover .card__text {
  @apply text-white;
}

group 和 peer 是状态标记,不是声明型 utility

Tailwind 与 UnoCSS 在这条机制上相同,失败方式却不同:Tailwind 会对这类未知 apply 项报错,UnoCSS 66.12.0 的默认 directives 可能只展开同组里的合法 utility、忽略 marker。没有编译错误,不代表 DOM 关系已经存在。

自定义 class 要区分注册方式与可见范围

业务样式优先通过组件或 class 组合复用。需要在 apply 中引用自定义样式时,要检查定义能否被当前文件看到。Tailwind v3 支持同一处理上下文里的部分自定义 class。v4 用 @utility 注册工具类,隔离的组件样式引用外部定义时还需要 @reference。UnoCSS 可以使用 rules 或 shortcuts。

普通 class、已注册 utility 和状态 marker,虽然都可能写在 HTML 的 class 中,却承担不同职责。把它们区分清楚,才能判断复用应当发生在组件、DOM 还是声明层。

UnoCSS 路径:SCSS 组织选择器,directives 生成声明

采用 UnoCSS 与 SCSS 时,SCSS 负责 BEM 拼接、状态嵌套和主题 map,directives 将工具类展开为声明。验证基础包括 UnoCSS 66.11.0、Wind3 与 Sass Embedded 1.105.1;新接入配置采用 Wind4,历史测量仍保留原预设。框架语法、预处理器和工具类生成分别验证。

最小配置保持明确

// uno.config.ts
import { defineConfig, presetWind4, transformerDirectives } from 'unocss';

export default defineConfig({
  content: { pipeline: false },
  presets: [presetWind4({ preflights: { reset: false } })],
  transformers: [transformerDirectives()],
});

content.pipeline: false 适用于这里的 apply-only 约定:模板保留语义类名,只在样式中消费工具类。它关闭构建管线内容提取,不关闭 directives;混合使用模板工具类时,恢复所需提取配置。

普通 Vue + Vite 注册 UnoCSS 与 Vue 插件时,保留默认 directives 阶段,并将 UnoCSS 放在 Vue 前:

// vite.config.ts
import vue from '@vitejs/plugin-vue';
import UnoCSS from 'unocss/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [UnoCSS(), vue()],
});

入口按集成文档引入 virtual:uno.css,Nuxt 则使用 @unocss/nuxt 模块并核对实际框架配置。

引擎、预设、源码转换与构建集成各自负责什么,以及普通工具类为什么常在两种插件顺序下都能工作,见《Vite 插件顺序:从 CSS v-bind() 失效说起》。

原实验里的 Wind3 没有另外导入通用 reset。Wind4 则默认内置 reset;已有项目已经处理基础样式、按钮和组件库主题时,可以用 preflights: { reset: false } 关闭它,同时保留所需主题变量和内部初始化。

Tailwind 路径:沿用现有工具,调整局部组织

Tailwind 项目同样可以让模板保留语义 class,在局部 CSS 中使用 apply。v4 的组件样式若独立处理,可以引用项目主样式里的主题与自定义定义:

<style scoped>
@reference "../../assets/css/app.css";

.resource-card {
  @apply flex gap-4 rounded-lg;
}
</style>

这里使用普通 CSS;SCSS 的 &__title 拼接、map 和循环不属于这条链路。可以直接写完整 BEM 选择器,保留元素归属与状态就近的原则。已有 Tailwind v3 + SCSS 项目则按当前配置检查,不为采用组织方式而同时升级工具。

下面关于变量、动态值与响应式的具体简写使用 UnoCSS。Tailwind 中采用对应 utility 或普通 CSS;复杂属性更适合原生声明时,继续直接书写。

UnoCSS 的 apply 约定

我会把静态视觉声明统一放进 @apply,让同一块样式只有一种主要表达方式。常用属性用工具类,复杂值和需要保留精确属性语义的地方使用任意属性。变量定义、描述符和运行时量测值则各自保留合适的语法;Vue 动态值直接放进 apply 时,沿用前面的插件顺序。

固定设计尺寸显式写单位

整理既有的 padding: 16px 时,我会先写成 p-16px,保持单位和值。不能只因默认根字号下数值相同,就换成基于 rem 刻度的写法;根字号改变后,两者的缩放行为不同。

已有设计系统要求使用间距刻度或 rem 时,继续遵循它。引入 UnoCSS 和调整尺寸体系是两项决策,拆开验证更容易发现布局变化来自哪里。

简单变量用 $,变量名写清用途

.resource-card {
  @apply text-$app-color-text-primary bg-$app-color-surface;
}

这里的 $ 是 UnoCSS 预设识别的简写。编译后仍然是 color: var(--app-color-text-primary),它和 SCSS 的 $root、$theme-tokens 变量属于不同机制。

UnoCSS 变量简写在构建期展开,CSS 变量在运行时随主题取值

--app-color-text-primary 比 --ink 长,但调用点能直接知道它的命名空间、类别和用途。组件公开变量也应该有自己的命名空间,例如 --common-button-size;第三方的 --el-* 则保留原有契约。

变量定义处的注释解释用途和边界。尤其是阴影,必须说明存的是「颜色」还是「整条阴影」,否则 shadow-$app-color-shadow 看着简洁,实际可能把一个颜色当成完整阴影值。

复合值和有歧义的值保留 var()

.resource-card {
  --resource-card-padding: 16px;
  @apply [border:1px_solid_var(--app-color-border)] [box-shadow:0_5px_22px_var(--app-color-shadow)] p-$resource-card-padding text-$app-color-text-primary;
}

上面的 --resource-card-padding 是定义,p-$resource-card-padding 是完整单变量引用,后两项则是复合值。任意值里的空格用 _ 表达,字面下划线需要按具体解析规则处理。

有 fallback 的 var(--x, 16px)、多层背景、CSS 字符串和需要类型提示的值,也不做机械替换。例如 text-[length:var(--app-title-size)] 已经明确表示字号,不能只因为里面有一个变量,就换成可能按颜色解释的 text-$app-title-size。

常用声明可以优先用等价工具类。涉及多值、类型提示或简写的重置范围时,按编译结果选择写法,具体例子见《工具类、任意值与任意属性怎么选》。

阴影和动画同样可以放进 @apply,但要核对变量存储的内容、时间函数和生成的 keyframes。@font-face、@property 中的描述符、CSS 自定义属性定义、SCSS 变量仍使用原语法。运行时测出的浮层坐标可以保留动态 style,不为统一静态语法改变状态流。

SCSS 中的 @apply 默认不加整组引号。其他预处理器如果会提前解析小数、括号或 calc(),可以使用 directives 支持的整组引号兼容写法,见官方说明。在本文验证的 Sass 链路中,前置 !hidden 会被 Sass 拒绝,后置 hidden! 可以通过;不要直接复制另一种预处理器里的写法。

动态视觉值可以直接写进 apply

固定布局可以在构建时确定,用户选择的字体、颜色却可能继续变化。工具类完整写在源码里,动态属性值由 Vue SFC 的 CSS v-bind() 提供:

<script setup lang="ts">
const props = defineProps<{ textFamily: string; textColor: string }>();
</script>

<template>
  <p class="font-preview">春江潮水连海平<br>The quick brown fox · 0123456789</p>
</template>

<style scoped lang="scss">
.font-preview {
  @apply px-12px py-8px rounded-6px text-20px leading-32px [font-family:v-bind('props.textFamily')] [color:v-bind('props.textColor')];
}
</style>

在前面的普通 Vue + Vite 配置中,可以直接使用这种写法,保留默认 directives 阶段和 UnoCSS 在前的顺序。样式只在复用或公开契约需要时定义中转变量;复杂绑定表达式使用 Vue 支持的引号形式。

扫描与声明转换的区别、两种顺序下绑定函数如何被处理,以及配图与实验记录,见编译过程分析。

把 font-family 移到选择器里,收益是字体声明能和同一元素的其他样式放在一起。没有统一的 @apply 约定时,也可以直接写 font-family: v-bind(textFamily),确实要复用时再加中转变量。底层仍会用 JS 更新内联 CSS 变量。font-family 从元素上的内联样式移到选择器后,层叠优先级会变,迁移时要和原有声明一起检查。

我不会把全部 :style 都改成这种写法。v-for 的行变量和 v-slot 的插槽变量不属于组件级 setup 状态;浮层量测坐标、SDK 样式对象、公开自定义属性契约也有各自的写入职责。列表项本身值得独立成组件时,可以利用每个实例的 CSS 变量;为了删除一个绑定而机械拆组件,反而增加阅读成本。Teleport 和 Transition 中的关键几何值,还要考虑变量注入与节点创建的时机。

SCSS 导入与 Tailwind CSS v4 有不同的构建前提,阶段调整按预处理器与插件顺序的分析核对,不将普通插件的数组调整直接换成 directives pre。

响应式与状态差异放在所属选择器里

我更常问「这个元素在什么条件下变成什么样」,所以基础样式、状态和响应式差异都围绕元素组织:

.resource-card {
  @apply grid p-24px lt-lg:(p-20px) lt-sm:(p-16px);
  &__actions {
    @apply flex gap-8px opacity-70 media-[(hover:none)]:(opacity-100);
  }
}

同一个源码样式块只写一条 @apply。基础工具类写在前面,相同条件合为一组。能放下一行就写在同一行,太长再续行。完整的条件链放在组前,例如 md:lt-lg:(...)。嵌套选择器和原生媒体块分别组织。

原生媒体查询里的基础工具类也可以按效果合并。LoL 职业库在低视口中把紧凑标题裁切到 1 像素,定位、尺寸、裁切和不换行共同实现这一个效果,可以写在同一条指令里。

@media (height <= 600px) {
  .intro--compact {
    @apply [clip-path:inset(50%)] absolute h-1px m--1px overflow-hidden p-0px w-1px whitespace-nowrap;
  }
}

UnoCSS 66.11.0 的 directives 内部会调用 expandVariantGroup,这里不需要为 @apply 再安装一份 variant-group transformer;模板 class 的分组属于另一个入口,需要对应配置。

Wind3 的默认断点是 sm 640px、md 768px、lg 1024px、xl 1280px、2xl 1536px。普通前缀从相应宽度开始生效,lt- 表达小于该断点的范围。默认值已经够用时,我会直接复用,避免维护一组仅有几十像素差异的新全局断点。自定义 breakpoints 会覆盖默认集合,需要自定义时应提供完整设计。

不过,960px 改成 1024px 属于布局决策,不能当成格式化;lt-sm 当前生成的 max-width: 639.9px 也和 max-width: 640px 有边界差异。Header、主栏和侧栏的断点要一起检查。

media-[(hover:none)] 表示主要输入设备无法方便地悬停,和小屏宽度、元素的 hover: 伪类都不同。减少动画可以用 motion-reduce:。定义变量的媒体块、特殊业务宽度、尚未验证的复杂条件,可以继续使用就近的原生 @media,不追求源码里一个媒体查询都不剩。

重叠条件要检查输出顺序

一次整理响应式样式时,我把条件组拆成了多条 @apply。在实际 Nuxt 构建链中,小屏标题区域的宽度由 331px 变成了 305px;按媒体块分别比较属性却没有发现差异。问题出在重叠条件间的层叠位置,单个块正确,并不能保证组合结果正确。

下图用简化 CSS 展示这个风险,数值用于说明层叠关系,不是当时页面的源码。

重叠媒体条件的声明相同,输出顺序不同,小屏最终宽度也不同

后来把同一选择器的条件放进一条指令,一起交给 directives 展开和排序,实际布局恢复了预期。这个组织方式也让同条件的属性更容易集中阅读。

示例编译脚本中,两个简单的 width 条件无论拆开还是合并,都产生了相同顺序,见编译探针。这个最小样例没有复现实际应用中的逆序,根因仍需结合完整集成分析;源码中存在异步处理,也不足以单独证明原因。迁移是否等价,最终要看消费者构建后的 CSS 和运行态。

这次整理后,项目的 72 组布局检查恢复一致,34 张对照截图逐字节相同。后续迁移仍然要覆盖重叠条件和边界宽度,这些检查不能被一次格式规则替代。

让属性保持顺序

看一个样式块时,我习惯先找布局和尺寸,再看文字、颜色和动效。同类声明有固定位置,改卡片内边距时就能直奔那一组,新增属性也容易放到合适的位置。同名声明和简写覆盖子属性时,我会先拆开重叠的写入。需要按顺序尝试的兼容回退,保留原来的次序。普通 CSS 的分组顺序可以配置在 Stylelint 的 order/properties-order 规则里。

写成 @apply 后,我按工具类名字典序找位置。卡片用 grid 布局,间距和内边距也都能在同一条指令里找到。

.resource-card {
  @apply gap-12px grid p-16px;
}

用 UnoCSS 66.12.0 的 Wind4 和 directives 编译,把工具类写成 p-16px grid gap-12px,产物仍然是 padding:16px;gap:12px;display:grid;。换成两条独立的指令,交换位置就可能改变样式。先 @apply p-16px 再 @apply pl-4px,左内边距是 4px。交换两条指令后,后写的 padding 把左内边距也设成了 16px。因此排序的范围先限定在一条指令内部,响应式分组和声明之间的覆盖顺序继续按实际输出判断。

拆开会互相覆盖的边框声明

博客的分割线原来先用 border: 0 清掉四边,再用 border-top 画线。两个任意属性在 UnoCSS 66.12.0 的 Wind4 中命中同一个规则索引,生成声明保留源码先后。把它们交换后,后写的 border 简写会把顶边一起清掉。用 Chromium 对照,分割线高度从 1px 降到 0px。搜索框的底边遇到的是同一个问题,交换后输入框少了 1px 高。

hr {
  @apply [border:0] [border-top:1px_solid_var(--line-color)] my-16px;
}

四条边可以独立写。分割线把三条无边框的边各设为零,顶部单独画线。搜索框同理,只把底边设为实线。两处改写后的四边计算样式和尺寸与原先正确顺序一致,交换新候选的先后也得到相同结果。遇到使用边框图片的元素,还要单独核对 border-image,原先的 border 简写也会重置它。

hr {
  @apply [border-bottom:0] [border-left:0] [border-right:0] [border-top:1px_solid_var(--line-color)] my-16px;
}

p-2 p-4 可以只保留需要的值。要表达顶部与其他三边的内边距不同,可以用一个 padding 简写写完,或者给互不重叠的边单独赋值。混用逻辑边和物理边时也要看书写模式,例如 padding-inline 在竖排下可能和 padding-top 争用同一条边。条件本来就不同的响应式覆盖,仍在条件命中的视口里检查结果。样式冲突的 Lint 规则

模板类名排序的边界

官方 unocss/order 能把静态的 class="p-4 flex" 排成 class="flex p-4"。脚本里的类串则可能还没拼完整,也可能交给一个按输入顺序取舍的函数。用 @unocss/eslint-plugin 66.12.0、ESLint 10.13.0 和 Wind3 跑 --fix,下面两段代码的求值结果都变了。

输入 自动修复后的变化
const className = `px-4 bg-${color}` 改成 const className = `bg- px-4${color}` 。传入 red,px-4 bg-red 变成 bg- px-4red。
const className = twMerge('p-4 p-2') 参数改成 'p-2 p-4',twMerge 的结果从 p-2 变成 p-4。

bg- 原本要和 ${color} 拼成一个类。规则单独排序插值前的文本,挪到了别的位置。类似的误改也出现在 UnoCSS 仓库的 Prettier 排序讨论 #5411 里。

twMerge() 则是另一回事。className 命中默认的变量名模式,规则沿着初始化表达式进入函数参数。twMerge() 在这两个内边距类中保留靠后的那个,重排直接改变了间距。这个参数检查入口来自 PR #5318。完整输入和输出见排序复现记录弹窗。

自定义排序先从 @apply 做起

sheng/unocss-apply-order 分别检查基础参数区和每个条件组内部的工具类字典序。基础区换行后仍是一段,条件组之间的先后要看生成样式。规则只检查候选都能解析、且各自对应不同规则索引的片段。

Chrome DevTools 的 Computed 面板按属性名字典序展示解析后的值,Styles 面板则保留样式表里的声明。

用 Prettier 按行宽折行

Prettier 3.9.10 能排版 CSS、SCSS 和 Vue 的样式块,但内置的 CSS printer 不会按 printWidth 拆长 @apply。我用 @sheng/prettier-config/wrap-apply 接管这部分排版。能放下一行时,基础工具类和条件组共用一行。放不下时,在完整候选之间续行,条件组和任意值内部保持完整。

{
  "plugins": ["@sheng/prettier-config/wrap-apply"],
  "printWidth": 120
}

使用包含 wrap-apply 入口的共享配置包,把插件加入项目的 Prettier 配置,再运行项目的格式化命令。Tailwind 社区的 prettier-plugin-tailwindcss-wrap-apply 也能折行。UnoCSS 工程还要确认 hover:(...)、任意值、转义、注释和 Vue 内嵌样式经过格式化后仍可编译。换行只调整候选间的空白,候选的字典序和写入冲突由 Stylelint 检查。

主题按变量维护,全局样式按所有者划分

样式写得紧凑以后,变量和选择器的组织会更影响可读性。工具类解决表达效率,主题数据和组件边界仍然需要自己设计。

同一个变量的深浅值就近放

先写一整段浅色变量,再写一整段深色变量,适合按主题整体检查;日常查看某个变量时,则需要来回搜索。我更倾向于以变量为索引,用 SCSS map 保存一对深浅值:

@use 'sass:list';

// 配对顺序:浅色、深色。
$theme-tokens: (/* 标题和主要文字的前景色。 */ 'app-color-text-primary': (#242833, #e7e9ed), /* 只存阴影颜色,不包含偏移和模糊参数。 */ 'app-color-shadow': (#14233312, #00000038));

:root {
  @each $name, $values in $theme-tokens {
    --#{$name}: #{list.nth($values, 1)};
  }
}
:root[data-theme='dark'] {
  @each $name, $values in $theme-tokens {
    --#{$name}: #{list.nth($values, 2)};
  }
}

这里减少的是源码维护成本。浏览器收到的仍是两套标准 CSS 变量定义,运行时切换主题的机制也没有改变。Sass map 只是组织数据的手段;更喜欢显式键名时,也可以使用包含 light / dark 的内层 map。

颜色、阴影色、背景、字号和层级按语义命名。组件库适配集中映射到应用 token,避免再维护一套互不相干的深色配色。纯固定值如果没有主题或跨组件语义,不必为了缩短任意值语法就强行抽成全局变量。

共享控件优先组件化

多个按钮都依赖 .result-action 一类全局 class 时,按钮的 hover、disabled、尺寸和焦点样式实际上已经形成了一份控件实现。它缺的只是明确的组件入口。

我会把这类样式移进按钮组件,让业务调用点保留事件和文案;稳定的视觉角色用 variant,反馈色用 tone,父级调整尺寸时通过公开 prop 或 CSS 变量。

<common-button variant="action" :aria-pressed="saved" @click="toggleSaved">
  <common-icon name="bookmark" />
</common-button>

封装要保留原生能力:普通按钮默认 type="button",提交按钮显式声明 submit;链接保留 href、target、rel;ARIA、disabled、form、事件和 tooltip 应到达真实控件。原来通过 ref 调用 .focus() 的地方,也要验证组件的焦点入口。Vue 的透传属性是其中一部分,不能用「包装后能显示」代替交互验收。

真正跨边界的自有 class 标明 global-

reset、主题变量、第三方样式适配、程序生成的 DOM,以及明确公开给父级的样式 hook,可能确实需要跨组件边界。这些自有 class 可以使用 global- 前缀,让维护者在调用点就意识到影响范围。

组件内部的 BEM class 不需要全部加前缀,第三方的 el-*、os-* 等固定 class 也不能改名。给 .result-action 改成 .global-result-action 只能标记边界,无法回答它为什么还没有封装成组件。

职责清楚的语义类名便于识别内部元素;需要长期供外部使用的入口,还要明确其公开性和兼容约束。

把约定交给 Lint,把等价性交给构建和浏览器

第七篇专门比较两边的规则、样式入口和排序边界,见《利用 Lint 规范写法》。

格式偏好只写在文档里,很容易在后续开发中逐渐偏离。我把可以静态识别的部分放进自己维护的 @sheng/stylelint-plugin,按项目选择启用:

规则 检查职责
unocss-prefer-apply 普通声明进入 apply,保留定义类语法
unocss-prefer-css-var-shorthand 已知无歧义的完整变量使用 $
unocss-prefer-responsive-variants 已知断点与明确媒体偏好使用变体
unocss-prefer-variant-groups 同条件分组、每组一行、条件共用一条指令
prefer-local-media-query 原生媒体差异靠近已有选择器
prefer-global-class-prefix 自有跨边界 class 显式标记

表中省略了实际规则名的 sheng/ 前缀。这些规则有不同适用范围,unocss-* 不应该加到纯 SCSS 或 Tailwind 项目上;媒体就近规则则可以独立使用。对于未知预设、特殊宽度、变量定义、复合值和第三方 class,规则需要有保守边界和明确例外。

这些 Stylelint 规则不执行整份 UnoCSS 配置,无法保证某个工具类一定生成了预期属性,也不能决定一个全局样式是否应该封装成组件。涉及移动声明、修改选择器或改变条件的检查,我不会做自动修复。

其中 unocss-prefer-apply 保留真正含有 Vue v-bind() 函数的声明,允许固定工具样式与动态供值并存。字符串或注释中碰巧出现 v-bind(...),不会成为普通声明的豁免理由。

模板里混进工具类,也要能检查出来

样式已经统一到 apply,模板里却仍然能写 class="flex p-4",这套约定就只做了一半。我先核对了现成规则,发现它们各有职责,不能直接拼出这里需要的限制:

候选 已有能力 这里的差距
vue/no-restricted-class 根据固定字符串或模式禁止类名 需要维护名单,且部分表达式不在提取范围内
UnoCSS ESLint 集成 排序、blocklist 等约束 没有「模板禁用当前引擎识别的全部工具类,apply 继续可用」的开关
better-unocss 的 no-restricted-classes 根据配置模式限制类名 同样需要描述禁用名单,不能直接代表项目真实的全部工具类

以 eslint-plugin-vue 10.11.1、ESLint 10.13.0 为例,给 vue/no-restricted-class 配置 flex / grid 后,静态 class 能命中,下面这个三元表达式没有诊断:

<div :class="compact ? 'flex' : 'grid'" />

这说明固定名单和表达式提取是两个不同的问题。该次探针保留了 16 种输入与真实诊断,包括数组、对象、逻辑分支和字面量拼接;版本升级后应重新验证,不能把这次结果推广成所有版本的结论。

UnoCSS 自己的 blocklist 也不适合拿来禁止模板 class。我在 66.11.0 上把 flex 加进真实配置的 blocklist,.resource-card { @apply flex p-4; } 最终只剩 padding: 1rem,display: flex 也被去掉了。它会影响工具样式的生成,无法单独约束工具类写在哪里。

因此我在 @sheng/eslint-plugin 增加了 ui-no-unocss-class-in-template,放进单独选择的 unocss-apply 分组。规则加载项目实际的 uno.config.ts,通过引擎判断 token;预设、自定义规则、shortcut、任意值和变体都按同一份配置识别。它不扫描 style 中的 @apply。

const config = {
  rules: {
    '@sheng/ui-no-unocss-class-in-template': [
      'error',
      {
        configPath: './uno.config.ts',
        checkDynamicClass: true,
        allowClasses: ['vendor-container'],
        allowPatterns: ['^vendor-widget-'],
      },
    ],
  },
};

示例里的例外要按项目实际需要填写。普通 BEM 类与没有注册成工具类的第三方名称自然通过;当第三方约定名恰好与 UnoCSS 工具类重名时,才精确放行。正则适合限定第三方前缀,不应该写成全部匹配,更不应该跳过整个第三方组件。

规则检查 Vue template 和 JSX / TSX,递归读取对象键、数组、三元及逻辑分支,也能计算无副作用的字面量拼接。它不执行函数或读取运行时变量。默认模式放过未知 class 表达式;上面的严格模式会把它们也报告出来。自己的 BEM 变体可以写成明确的对象键与条件;第三方动态透传确实无法检查时,再局部 disable 并写清原因。Vue template 内的 HTML disable 注释需要框架 ESLint preset 的 processor 和 vue/comment-directive,只装 parser 不会生效。

严格模式仍不等于完整的数据流证明。未知的 v-bind="attrs"、JSX props spread、动态属性名、attributify 与运行时 DOM 写入都需要另外审查;纯 group / peer 标记也未必单独生成 CSS。实际配置的 blocklist 继续生效,规则不会为了识别而改变构建配置。

这里还有一个实现边界:ESLint visitor 是同步接口,UnoCSS 配置加载和 token 解析是异步接口。我沿用官方 ESLint 集成的思路,用 synckit 的持久 Node worker 连接两者,按文件批量传入去重后的 class 值,并缓存 generator。首次加载有额外成本;配置改动后需要重启 ESLint 服务。配置错误或 worker 超时会产生诊断,不会当作检查成功。

这条规则目前使用 UnoCSS 66.11.0 引擎,与应用的版本保持一致;升级时一起验证。测试覆盖自定义规则、shortcut、不同配置之间的隔离、第三方例外、严格模式和关闭规则后的行为。实际 Nuxt 配置也补了正反例,确认普通 BEM 与 apply 通过,条件工具类和未知动态 class 被阻断。规则没有自动修复,语义类名和层叠仍由开发者决定。

完整实现与接入示例见完整源码与接入方法弹窗。

动态 style 只提示明确的迁移候选

样式层已经能消费组件变量后,我又加了 @sheng/vue-prefer-css-v-bind,以 warning 提醒仍留在模板里的简单动态视觉绑定。例如同组件中的 :style="{ fontFamily: textFamily }",可以考虑迁到 scoped style;固定的像素值则继续由 vue-no-static-px-inline-style 检查。

const config = {
  rules: {
    '@sheng/vue-prefer-css-v-bind': 'warn',
  },
};

这条规则只处理单个 script setup、本地 scoped style、普通 HTML 元素和明确的视觉属性。对象中混有尺寸、定位、自定义属性、spread,或者位于列表、插槽、Teleport、Transition 范围时整条保留。明确的 const 对象与 Vue computed 对象也可检查;未知工厂、多语句 getter、函数调用和动态键不推断。

插件顺序可另用 @sheng/vue-vite-unocss-plugin-order warning 保护项目默认。它检查明确的官方 import 与静态调用,遇到外部数组、spread、包装器时不猜测,也不自动重排。

// 其余配置已注册 @sheng 插件与 TS parser。
const config = {
  files: ['**/vite*.config.ts'],
  rules: { '@sheng/vue-vite-unocss-plugin-order': 'warn' },
};

这条提示不证明完整构建链正确,仍需检查产物和状态更新。具体的阶段追踪、残留语法与浏览器验证方法,见插件顺序的验证。

规则不会执行 computed,也不知道每个 SDK 的契约。项目可以精确忽略属性或样式对象变量,必要时带原因局部关闭。它没有 autofix:维护者仍需选择语义 class,核对原行内声明与新规则的优先级,并验证更新时机。完整条件和源码在模板样式规则与测试弹窗中。

允许 apply 语法,不等于检查了工具类

在 Tailwind v3 的一个实际样本中,@apply transition-colors ease; 通过了编辑器、Stylelint 和 git hook,直到构建调用 Tailwind 才报错:

The `ease` class does not exist. If `ease` is a custom class,
make sure it is defined within a `@layer` directive.

Stylelint 可以检查 CSS AST 和项目约定,git hook 只负责运行配置过的命令。两者都不会因为允许 @apply 这个 at-rule,就自动执行工具类解析。要发现未知 utility,必须让实际生成工具参与检查。

Tailwind 样本中各层检查为何没有解析 ease

这个思路同样适用于 UnoCSS。缺失且没有 fallback 的 theme() 路径、不存在的 @screen 断点会让 directives 抛错,未知 apply 项却可能被过滤。检查既要捕获转换错误,也要核对每个预期 token 是否被解析,以及生成属性是否正确。

轻量诊断与真实解析分别检查

轻量规则适合给出明确、及时的建议。例如 @sheng/stylelint-plugin 的 tailwind-apply-no-css-value 针对 Tailwind 的已知错法,并允许按自定义 utility 放行。它可以提醒裸 ease、linear 与 group / peer marker,不应扩张成所有工具共用的固定词表。

更多未知项需要读取项目实际配置:

  • Tailwind 按所用版本加载编译器、主题和自定义 utility;v3 的 PostCSS 脚本不能直接代表 v4。
  • UnoCSS 按当前预设、rules、shortcuts、variants 和 blocklist 识别输入;分组要经过真实 directives 路径。
  • Vue SFC、预处理器和隔离样式块还需要相同的导入与引用上下文。缺失共享定义可能造成误报,完整构建继续负责其余插件、作用域和最终层叠。

文件级检查可以先解析 SFC style 块,再按项目链路编译样式。完整 Tailwind v3 适配示例见按文件运行编译检查弹窗;它展示如何提前验证,接入 v4 或 UnoCSS 时需要替换解析入口。

日常提交控制范围,专项清理显式执行

按文件编译比轻量诊断更重,不宜每次提交默认扫描整个仓库。日常可以让 lint-staged 传入本次改动文件,CI 再运行相应检查与完整构建,历史清理则显式传目录。

{
  "*.{css,scss,vue}": ["stylelint", "pnpm lint:utilities:compile"]
}

这里的 lint:utilities:compile 是需要项目提供的命令,负责接收文件参数并选择实际工具链。它不默认扫全仓,也不把文件级检查冒充完整应用构建。

原 Tailwind 样本还保留一套轻量静态规则和可复制脚本。下面的诊断演示固定在历史名单上,其中 opacity scale 不能推广到新版或自定义主题;当前工程应优先复用实际维护的插件与配置。

Stylelint 规则诊断示例正在加载代码工作区...

完整规则、脚本与测试见Tailwind 护栏源码弹窗。检查思路可以复用,具体实现仍有版本与工具边界。

静态护栏之外的验证

真正落地还要检查三件事:

  1. 真实配置覆盖源码。Vue SFC 和独立 SCSS 都进入命令,parser 能正确分发;用应失败和应通过的样例,确认命中的 ruleId 与位置。
  2. 生产编译保持语义。比较完整选择器、条件、属性、重置范围、important 和层叠顺序;检查最终产物没有残留 @apply,也没有悄悄漏掉未知工具类。
  3. 浏览器覆盖有差异的状态。检查新旧断点两侧及恰好断点处、深浅主题、无悬停设备、展开弹层、焦点和原生提交,记录 computed style 或布局尺寸。

源码包保留了一张资料卡片、主题 map 和体积实验。静态预览加载预编译 CSS,支持切换深浅主题和收藏状态;改 SCSS 后在本地重新构建。可以在源码包中查看例子与规则实现:

主题、BEM 状态与条件分组正在加载代码工作区...

在源码包目录执行 pnpm install、pnpm build、pnpm measure,可以重新生成示例 CSS 与测量报告。实验里的组件数量、重复次数和样式组合都可以调整;真正要决定产物成本时,用自己的页面和构建方式测量更有意义。

总结

语义类名表达职责,apply 组织可展开的视觉声明,group / peer 等 DOM 标记继续留在真实元素上。变量、动态值、响应式和主题遵循各自的语义;SCSS 与 UnoCSS 的专有简写按当前链路使用。固定尺寸显式保留单位,复合变量值与重置声明按最终属性判断;共享控件通过组件接口维护,确需跨边界的自有 class 再标明 global-。

Lint 能维持可静态识别的约定,工具类名称相近、检查通过或单个媒体块属性一致,都不足以证明迁移等价。最终仍要比较完整构建产物,在真实页面检查属性语义、层叠、布局、主题与交互;未知预设、动态表达式和第三方契约需要人工确认。

上一篇:CSS 如何减少重复。

下一篇:Tailwind CSS 与 UnoCSS 的兼容边界。

UnoCSS 工具类排序的复现记录

打开原文件 utility-order-report.json

{
  "versions": {
    "node": "26.12.0",
    "eslint": "10.13.0",
    "eslintPluginUnoCSS": "66.12.0",
    "unoCSS": "66.12.0",
    "tailwindMerge": "3.7.0"
  },
  "order": {
    "preset": "wind3",
    "interpolation": {
      "input": "const className = `px-4 bg-${color}`",
      "output": "const className = `bg- px-4${color}`",
      "valueBefore": "px-4 bg-red",
      "valueAfter": "bg- px-4red"
    },
    "merge": {
      "input": "const className = twMerge('p-4 p-2')",
      "output": "const className = twMerge('p-2 p-4')",
      "valueBefore": "p-2",
      "valueAfter": "p-4"
    }
  },
  "directives": {
    "preset": "wind4",
    "apply": [
      {
        "input": ".resource-card { @apply p-16px grid gap-12px; }",
        "css": ".resource-card { padding:16px;gap:12px;display:grid; }"
      },
      {
        "input": ".resource-card { @apply grid gap-12px p-16px; }",
        "css": ".resource-card { padding:16px;gap:12px;display:grid; }"
      }
    ],
    "separateApply": [
      {
        "input": ".resource-card { @apply p-16px; @apply pl-4px; }",
        "css": ".resource-card { padding:16px; padding-left:4px; }"
      },
      {
        "input": ".resource-card { @apply pl-4px; @apply p-16px; }",
        "css": ".resource-card { padding-left:4px; padding:16px; }"
      }
    ]
  }
}
模板样式规则:Node 源码与实际配置测试

打开原文件 FILES.json

模板工具类、CSS v-bind() 迁移提示和 Vite 插件顺序规则的完整实现与同源测试放在下面的源码包里。这是只读源码工作区,实际诊断由 Node 中的测试和 ESLint 命令生成;工具类识别依赖 Node worker,后两条规则分别只分析当前 SFC 和配置文件。

读取 /files/my-unocss-best-practices/kits/unocss-style-practice/ 下的 README.md、MANIFEST.json、FILES.json。
按 AGENT_PROMPT.md 接入 copy/eslint 中的规则、测试和实际 UnoCSS 配置;第三方例外按真实重名情况填写。
先运行正反例与项目检查,再决定是否开启严格动态检查,不自动搬动模板 class。
模板样式规则:源码与实际配置测试正在加载代码工作区...
文件级编译护栏的实现

Tailwind v3 的文件级编译适配

本节保留 Tailwind v3 + Sass + PostCSS 的实现样本,使用 v4 或 UnoCSS 时需调整实际编译入口和上下文。轻量黑名单能挡住 ease,但挡不住所有 unknown utility。更接近真实构建的办法,是对本次改动的样式文件跑一次 Tailwind/PostCSS 编译。

脚本的大致流程是:

  1. 收集传入的 .vue、.css、.scss 文件。
  2. 如果是 Vue SFC,用 @vue/compiler-sfc 解析 <style> 块。
  3. 如果是 SCSS / Sass,用 sass-embedded 先编译成 CSS。
  4. 构造一个最小输入,把样式交给 Tailwind 的 PostCSS 插件。
  5. 如果 Tailwind 报 unknown utility,就把文件、style 块起始行和建议打印出来。

核心片段大概是这样:

// scripts/check-tailwind-compile.mjs
function createCompileInput(block) {
  const css = isScssLang(block.lang) ? compileScss(block) : block.content;

  return ['@tailwind utilities;', '', `/* file: ${styleBlockLabel(block)} */`, css].join('\n');
}

function createProcessor() {
  return postcss([
    tailwindcss({
      config: TAILWIND_CONFIG_PATH,
      content: [],
    }),
  ]);
}

async function checkStyleBlock(block) {
  const processor = createProcessor();
  const input = createCompileInput(block);

  await processor.process(input, {
    from: `${block.filePath}${block.index == null ? '' : `?style=${block.index}`}`,
  });
}

这层比黑名单准,因为它真的让 Tailwind 判断 utility 是否存在。它也比完整 nuxt build 轻,因为它只编译传入文件里的 style,不启动整站构建。

两层 Tailwind @apply 护栏

Tailwind @apply 护栏源码

打开原文件 FILES.json

Tailwind @apply 护栏源码正在加载代码工作区...