前端构建工具【免费下载链接】unocssThe instant on-demand atomic CSS engine.项目地址https://gitcode.com/GitHub_Trending/un/unocss点击查看免费下载UnoCSS 为工程化质量保障提供了官方 ESLint 集成unocss/eslint-plugin推荐通过unocss/eslint-config引入。本文以仓库内 docs/integrations/eslint.md 与 packages-integrations/eslint-plugin/README.md 为核心骨架结合packages-integrations/eslint-plugin的源码与测试完整讲解插件的安装、Flat Config /.eslintrc两种接入方式、order、order-attributify、blocklist、enforce-class-compile四条规则的语义与全部可选参数并深入其底层工作原理。读完你可以在任何 Vue / React / Svelte 项目中落地 UnoCSS 的类名排序与禁用规则检查并理解规则如何直接复用 UnoCSS 引擎的真实生成器做判断。一、为什么需要 UnoCSS 的 ESLint 插件UnoCSS 按需生成原子化 CSS一个元素的样式由class属性中的一串工具类名决定。随着类名增多两个工程问题随之而来顺序不一致同一个类名集合在不同文件里书写顺序不同生成的 CSS 规则顺序也不同影响层叠结果代码评审时也容易反复争论。禁用类名无法拦截项目里想淘汰bg-red-500、border等工具类或在多套设计系统之间禁用某类命名纯靠人肉 review 难以覆盖全局。官方 ESLint 插件把这些问题交给静态检查与自动修复解决。它的核心亮点在于规则不是靠硬编码的正则匹配而是真正加载你的uno.config.ts调用 UnoCSS 引擎对类名进行解析、排序与拦截判断因此结果与运行时构建完全一致。这一点从 worker.ts 中可以看到它通过loadConfig读取配置并用createGenerator构造真实的 UnoCSS 生成器规则侧再通过synckit的createSyncFn同步调用 worker见 _.ts。二、安装插件本体为unocss/eslint-plugin推荐直接安装封装好的unocss/eslint-config它内部依赖并导出了插件见 eslint-config/src/index.ts 与 eslint-config/src/flat.tspnpm add -D unocss/eslint-configyarn add -D unocss/eslint-confignpm install -D unocss/eslint-configbun add -D unocss/eslint-config前提条件规则运行需要读取 UnoCSS 配置文件。如果项目根目录没有uno.config.tsworker 会抛出错误提示先创建配置文件见 worker.ts 中的报错逻辑。三、两种 ESLint 配置风格的接入3.1 Flat Config 风格ESLint 9 默认在eslint.config.js中引入 flat 配置import unocss from unocss/eslint-config/flat export default [ unocss, // other configs ]unocss/eslint-config/flat子路径导出的是插件预置的 flat 配置对象。从源码 configs/flat.ts 可以看到它注册了unocss插件命名空间并默认开启两条 warn 级规则const flatConfig { plugins: { unocss: plugin }, rules: { unocss/order: warn, unocss/order-attributify: warn, }, }3.2 传统.eslintrc风格{ extends: [ unocss ] }对应 legacy 推荐配置见 configs/recommended.ts注册unocss插件并同样只默认开启order与order-attributify两条 warn 规则。两个配置对象通过 index.ts 统一挂在configs.recommended与configs.flat上这也是unocss.configs.flat这种写法的来源。四、规则总览规则名前缀取决于配置风格Flat configunocss/rule-nameLegacy.eslintrcunocss/rule-name可用的规则注册于 plugin.ts规则名作用默认开启order强制class属性中工具类按特定顺序排列是warnorder-attributify强制 attributify 属性按特定顺序排列是warnblocklist禁用配置blocklist中指定的类名否enforce-class-compile强制类名使用:uno:编译前缀否特别说明order-attributify只排序 attributify属性本身不会对属性值内部的工具类排序例如un-beforetext-center font-sans color-gray中的内容不会被重排——这种值内部的排序仍由order负责。五、order类选择器排序规则5.1 基本行为order检查class/className属性源码 constants.ts 中的CLASS_FIELDS [class, classname]对字符串中的工具类调用 UnoCSS 引擎重新排序乱序时报UnoCSS utilities are not ordered并自动修复fixable: code。它覆盖的语法形式非常广见 order.ts 与 order.test.tsJSX/TSXclassNamemx1 m1 mr-1、className{...}、模板字符串className{...}、String.raw、带插值的模板字符串只重排纯文本片段。Vue 模板class字面量与:class绑定中的字符串字面量。Svelteclass...及其{test ? a : b}三元表达式。函数调用clsx(...)、classnames(...)以及你通过选项指定的任意工具函数支持字符串、模板字符串、条件表达式、逻辑表达式、对象键值、数组嵌套、cva/tv变体对象等。变量声明变量名匹配的字符串字面量、对象字面量含嵌套、as const satisfies类型断言见order-unoVariables-satisfies测试组。一个 Vue 模板示例!-- 修改前 -- div classmx1 m1 mr-1/div !-- 修改后自动修复 -- div classm1 mx1 mr-1/divSvelte 中的示例见 order.test.ts!-- 修改前 -- div classmr-1 ml-1/div !-- 修改后 -- div classml-1 mr-1/div5.2 排序原理复用引擎而非硬编码order之所以懂UnoCSS 的排序规则是因为它调用了共享的排序实现 sort-rules.ts。该实现的关键步骤先用parseVariantGroup展开变体组再用splitVariantGroupBody切分每个工具类逐个调用uno.parseToken(i)让引擎真正解析工具类解析不出的视为未知类名保持原位不动只排序已知类名用解析结果中的规则序号token[0][0]加上变体层数权重variantHandlers.length * 100_000计算排序键同序号时按字典序比较排序后重新用collapseVariantGroup收起变体组最后把未知类名拼回头部。这也解释了为什么order要求项目存在uno.config.ts排序顺序完全由你的 preset如presetWind3与自定义规则决定。5.3order规则选项order接收一个可选的 options 对象schema 见 order.tsunoFunctionsstring[]标记哪些函数调用需要检查。这些是普通函数名而非模式匹配时忽略大小写。默认[clsx, classnames]。unoVariablesstring[]标记哪些变量声明需要检查。这些是带i标志的正则模式。默认[^cls, classNames?$]例如会匹配变量名clsButton与buttonClassNames。自定义示例export default [ unocss, { rules: { unocss/order: [warn, { unoFunctions: [clsx, classnames, cva, tv], // 检查这些工具函数的入参 unoVariables: [^cls, classNames?$, ^theme], // 匹配 themeDashboard 等变量 }], }, }, ]对应测试见 order.test.ts 中的order-unoFunctions含cva({ variants: { size: { small: px-2 text-sm py-1 } } })这类变体对象的重排与order-unoVariables两组用例。六、order-attributifyattributify 属性排序规则如果你启用了 preset-attributifyHTML 元素会写成这样div text-center font-sans color-gray un-beforetext-center font-sans color-gray /order-attributify专门对这些无值的 attributify 属性如text-center、font-sans按 UnoCSS 排序规则重排。从 order-attributify.ts 的源码可以看到它只处理 Vue 模板的VStartTag过滤出所有无值属性排除style、class、classname、value等原生属性见IGNORE_ATTRIBUTES把这些属性名拼成字符串交给syncAction(..., sort, ...)排序修复时用magic-string删除乱序属性并在第一个属性位置重写源码 order-attributify.ts。再次强调它不处理属性值内部un-beforetext-center font-sans color-gray的值内部乱序要交给order检查。七、blocklist禁用指定工具类可选规则7.1 规则语义blocklist不是默认开启的规则。启用后当代码中出现 UnoCSS 配置blocklist中列出的工具类时会抛出警告或错误。它既检查class字面量Vueclass/:class、JSXclassName、Svelteclass也检查attributify 无值属性名见 blocklist.ts 的VStartTag分支。报错消息格式为{{name}} is in blocklist{{reason}}即默认展示被禁的类名配置了自定义消息时追加: 你的消息。7.2 启用方式import unocss from unocss/eslint-config/flat export default [ unocss, { rules: { unocss/blocklist: error, // 或 warn }, }, ]{ extends: [unocss], rules: { unocss/blocklist: error } }仓库自带的 fixtures 就是这么用的fixtures/eslint.config.ts。7.3 自定义拦截消息你可以为被禁规则定制消息让提示更有指导性。消息可以是静态字符串或接收类名返回字符串的函数函数形式可结合原始类名动态生成建议export default defineConfig({ blocklist: [ [bg-red-500, { message: Use bg-red-600 instead }], [/-auto$/, { message: s Use ${s.replace(/-auto$/, -a)} instead }], // 例如 my-auto 被禁用时提示Use my-a instead ], })注意这里同时用到了两种 blocklist 条目写法bg-red-500字符串字面量以及[匹配器, { message }]元组形式——元组中匹配器可以是正则、字符串或接收类名返回布尔值的函数message的取值函数在 worker.ts 中按raw类名求值。测试 blocklist.test.ts 与规则目录下的 uno.config.ts 覆盖了静态消息、动态匹配、动态消息三类场景例如h-auto被提示改为h-a。7.4 底层判定流程blocklist的判定同样发生在 worker 中worker.ts先对类名字符串执行uno.applyExtractors提取工具类再对每个提取结果依次做uno.getBlocked(raw)直接命中、config.preprocess预处理、matchVariants匹配变体后的间接命中三层检查从而保证被禁类名即使带变体前缀如hover:也能被识别。八、enforce-class-compile强制类编译前缀可选规则8.1 规则语义与修复能力enforce-class-compile专为配合 compile class transformer 设计当class属性或:class指令的内容不以:uno:开头时报告prefix::uno:is missing并且默认自动为所有 class 属性与指令补上:uno:前缀把长串工具类编译为带哈希的短类名。!-- 修改前 -- div classmr-1/div !-- 自动修复后 -- div class:uno: mr-1/div它覆盖 Vue 中的多种绑定形态见 enforce-class-compile.test.ts 与 enforce-class-compile.tsclassmr-1静态属性:classmr-1字符串字面量:classcondition ? :uno: mr-1 : :uno: ml-1三元表达式修复两侧:class{mr-1: condition}对象字面量键名以及{flex}简写属性会展开为{:uno: flex: flex}:classmr-1模板字符串。8.2 规则选项prefixstring编译前缀必须与transformerCompileClass的触发词一致用于配合自定义前缀。默认:uno:。enableFixboolean设为false时只报告不自动修复适合渐进式迁移先把存量代码标红再逐步手动接入。默认true。import unocss from unocss/eslint-config/flat export default [ unocss, { rules: { unocss/enforce-class-compile: [warn, { prefix: :uno:, enableFix: true, // 迁移期可设为 false仅报告 }], }, }, ]8.3 与 compile-class transformer 的配合前提enforce-class-compile的prefix选项本质上对应transformerCompileClass的trigger参数——后者默认匹配:uno:正则见 transformer-compile-class/src/index.ts两者必须保持一致否则 ESLint 补上的前缀在构建时不会被 transformer 识别。如果你自定义了 trigger例如通过trigger正则或:uno-名称:命名编译类请同步修改本规则的prefix。兼容性注意该规则目前只支持 Vue源码中scriptVisitor对 JSX 与 Svelte 分支留了todo: add support | NEED HELP占位见 enforce-class-compile.ts。Svelte 场景建议改用svelte-scoped模式若需要在 JSX 中使用可向项目提交 PR 补全。九、可选规则统一启用模板以下两段模板供整体参考来自官方文档可按需把warn换成error或追加 options 数组import unocss from unocss/eslint-config/flat export default [ unocss, { rules: { unocss/blocklist: warn, // 或 error unocss/enforce-class-compile: [warn, { /* options */ }], }, }, ]{ extends: [unocss], rules: { unocss/blocklist: warn, unocss/enforce-class-compile: [warn, { prefix: :uno: }] } }十、底层工作原理worker 线程 真实引擎规则与 UnoCSS 引擎之间隔着一层精心设计的桥接理解它有助于排查规则和构建结果不一致之类的问题规则侧同步_.ts 用synckit的createSyncFn(join(distDir, worker.mjs))把sort/blocklist动作同步派发到 workerdist/worker.mjs由 worker.ts 通过runAsWorker注册。Worker 侧异步worker.ts 用loadConfig加载 UnoCSS 配置createGenerator({ ...config, warn: false })构造生成器并按缓存键显式configPath、文件所在目录、process.cwd()缓存生成器实例。多仓库monorepo支持未显式指定configPath时worker 从被检查文件所在目录向上查找配置文件getSearchCwd见 worker.ts因此每个子包可以使用自己的uno.config.ts。处理器虚拟路径markdown / MDX 等经 ESLint processor 生成的虚拟文件路径形如/path/to/source.ext/virtual_file.ext会被剥离出真实目录再定位配置。如果你需要强制规则使用某个特定配置文件比如项目根与 lint 入口不一致时可以在 ESLint 配置的settings中指定export default [ unocss, { settings: { unocss: { configPath: ./uno.config.ts, // 显式指定配置文件 }, }, }, ]这个settings.unocss.configPath的类型声明定义在 types.ts测试文件中也普遍使用它指向各自的uno.config.ts如 order.test.ts。十一、运行与验证在 fixtures 目录验证插件效果cd packages-integrations/eslint-plugin/fixtures eslint ./srcfixtures 仓库提供了现成的验证素材fixtures/src/App.vue、fixtures/src/app.tsx、fixtures/src/page.svelte配合 fixtures/eslint.config.ts开启了unocss/blocklist: error与 fixtures/uno.config.ts配置了presetWind3、variant-group transformer 与 blocklist 匹配器即可跑通完整链路。也可以直接运行规则测试确认行为符合预期测试均基于eslint-vitest-rule-tester与真实 ESLint 运行时行为一致order.test.ts覆盖 Vue / JSX / Svelte 三端与unoFunctions/unoVariables两个选项blocklist.test.ts覆盖静态 / 动态 blocklist 与自定义消息enforce-class-compile.test.ts覆盖前缀补全、自定义 prefix、enableFix: false只报不改等场景。十二、最佳实践小结最小起步安装unocss/eslint-configFlat 或.eslintrc二选一接入即可获得order与order-attributify的 warn 级排序检查确保项目根有uno.config.ts。渐进开启可选规则先以warn启用blocklist与enforce-class-compile配合enableFix: false完成存量迁移后再升级为error并开启自动修复。统一工具函数名单如果项目使用cva、tv、superclass等组合类名工具记得把它们加入order的unoFunctions否则这些函数体内的类名不会被检查。prefix 保持一致使用 compile-class 工作流时enforce-class-compile的prefix必须与transformerCompileClass的 trigger 完全一致。结语unocss/eslint-plugin的价值在于把类名排序、禁用拦截、编译前缀强制这些与 UnoCSS 引擎强耦合的检查做成了标准化的 ESLint 规则并且直接复用真实的 UnoCSS 生成器杜绝了 lint 结果与构建结果两张皮的问题。结合order/order-attributify的自动修复能力它能让团队在原子化 CSS 的写法上保持高度一致是 UnoCSS 生产级工程化中值得优先接入的一环。赞分享前端构建工具【免费下载链接】unocssThe instant on-demand atomic CSS engine.项目地址https://gitcode.com/GitHub_Trending/un/unocss点击查看免费下载相关推荐WebdriverIO ESLint 规则插件 eslint-plugin-wdio 完全指南从安装配置到四类规则的源码级解析WebdriverIO ESLint 规则插件 eslint plugin wdio 完全指南从安装配置到四类规则的源码级解析 eslint plugin w测试质量保障TanStack Query 官方 ESLint 插件tanstack/eslint-plugin-query 安装配置与 8 条规则源码级解析TanStack Query 官方 ESLint 插件tanstack/eslint plugin query 安装配置与 8 条规则源码级解析 TanSt前端缓存状态管理Gutenberg 官方 ESLint 插件 wordpress/eslint-plugin 完全指南配置预设、内置规则与 flat config 迁移实战Gutenberg 官方 ESLint 插件 wordpress/eslint plugin 完全指南配置预设、内置规则与 flat config 迁移实战后端前端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考