企业官网建设流程全解析

UnoCSS ESLint 官方配置指南：@unocss/eslint-config 的用法、四条规则与源码实现解析

【免费下载链接】unocssThe instant on-demand atomic CSS engine.项目地址: https://gitcode.com/GitHub_Trending/un/unocss

本篇指南围绕 UnoCSS 官方 ESLint 集成包@unocss/eslint-config展开，覆盖安装方式、Flat Config 与 legacy.eslintrc两种配置风格的接入方法、全部四条内置规则（order、order-attributify、blocklist、enforce-class-compile）的完整选项说明，并结合仓库中packages-integrations/eslint-plugin的源码实现，解释默认规则集、规则前缀命名差异与自动修复（fixable）的底层工作方式，帮助你在项目中规范原子类顺序、拦截禁用工具类，并与 compile-class 转换器协同工作。

一、这是什么：@unocss/eslint-config 的定位

@unocss/eslint-config是 UnoCSS 提供的 ESLint 配置包，用于在代码提交/保存阶段对模板与脚本中的 UnoCSS 类名做静态检查，核心能力包括：

• 强制 class 选择器按规则排序（order）；
• 强制 attributify 属性按规则排序（order-attributify）；
• 拦截命中blocklist的工具类（blocklist，可选开启）；
• 强制 class 属性以:uno:前缀开头，配合 compile-class 转换器（enforce-class-compile，可选开启）。

该包本身非常薄，实际规则全部由@unocss/eslint-plugin实现。从源码结构看，eslint-config 包 的唯一依赖就是@unocss/eslint-plugin（workspace 引用），它只负责以两种配置风格“打包”出即开即用的配置对象：

• 入口.（legacy）：见 src/index.ts，内容为extends: ['plugin:@unocss/recommended']，供.eslintrc风格extends使用；
• 入口./flat：见 src/flat.ts，即export default plugin.configs.flat，供 ESLint Flat Config 直接放入数组使用。

两条入口最终都落在 eslint-plugin 的规则注册表 上，那里注册了全部四条规则：

// packages-integrations/eslint-plugin/src/plugin.ts export const plugin: UnoCSSEslintPlugin = { rules: { order, 'order-attributify': orderAttributify, blocklist, 'enforce-class-compile': enforceClassCompile, }, }

二、安装

按所用包管理器安装到开发依赖中：

pnpm add -D @unocss/eslint-config

yarn add -D @unocss/eslint-config

npm install -D @unocss/eslint-config

bun add -D @unocss/eslint-config

三、接入方式：Flat Config 与 legacy .eslintrc

3.1 Flat Config 风格（eslint.config.js）

import unocss from '@unocss/eslint-config/flat' export default [ unocss, // other configs ]

从源码看，unocss这个配置对象就是 configs/flat.ts 导出的内容，它注册了unocss插件名并默认开启两条排序规则：

const flatConfig: UnoCSSEslintFlatConfig = { plugins: { unocss: plugin, }, rules: { 'unocss/order': 'warn', 'unocss/order-attributify': 'warn', } as const, }

仓库内的测试 fixture 也给出了一个带可选规则的真实用法示例（见 fixtures/eslint.config.ts）：

import antfu from '@antfu/eslint-config' import unocss from '../src' export default antfu( { unocss: false, svelte: false }, unocss.configs.flat, { rules: { 'unocss/blocklist': 'error', }, }, )

可以看出可选规则是通过在同级配置对象中单独声明rules来覆盖/追加的。

3.2 legacy.eslintrc风格

{ "extends": [ "@unocss" ] }

对应的 recommended 配置 为：

const recommendedConfig: UnoCSSEslintRecommendedConfig = { plugins: ['@unocss'], rules: { '@unocss/order': 'warn', '@unocss/order-attributify': 'warn', } as const, }

两种风格的差异汇总：

四、内置规则总览

4.1order：类名顺序检查

order规则检查 class 字符串中的工具类顺序是否与 UnoCSS 实际输出顺序一致。它支持fixable: 'code'（自动修复），其 schema 定义于 rules/order.ts。

适用位置：规则不仅检查模板里的class属性，还会检查 JS/TS 代码中“看起来像 UnoCSS 类名”的位置，通过两个选项来识别：

• unoFunctions(string[]) —— 匹配函数名的函数调用（如clsx('text-center', ...)）。注意是普通名称精确匹配（大小写不敏感），不是模式。默认值：['clsx', 'classnames']。
• unoVariables(string[]) —— 匹配变量声明名的正则（自动附加i标志）。默认值：['^cls', 'classNames?$']，例如会命中变量名clsButton、buttonClassNames。

默认值可以在源码中直接确认：

// rules/order.ts defaultOptions: [ { unoFunctions: ['clsx', 'classnames'], unoVariables: ['^cls', 'classNames?$'], // for example `clsButton = ''` or `buttonClassNames = {}` }, ],

自定义示例（Flat Config）：

{ rules: { 'unocss/order': ['warn', { unoFunctions: ['clsx', 'classnames', 'cva'], unoVariables: ['^cls', 'classNames?$'], }], }, }

源码级实现要点：order规则拿到候选类名字符串后，并不是自己排序，而是通过 rules/_.ts 中的syncAction把sort操作委托给一个 UnoCSS worker，排序结果来自真实的 UnoCSS 解析流程，并使用context.settings.unocss?.configPath指向的 UnoCSS 配置——也就是说，排序基准与你项目里uno.config.ts的实际解析结果保持一致，而不是硬编码的一套顺序。相关测试见 order.test.ts。

4.2order-attributify：attributify 属性顺序

开启preset-attributify时，模板上会出现大量 attributify 属性（如un-bg、un-text等）。order-attributify会对这些属性名本身排序。注意其边界：它不会进入属性值内部去排序值里拼写的工具类，值内部顺序交给order规则处理。

4.3blocklist：拦截禁用类（可选）

当命中blocklist中列出的工具类时抛出警告或错误。blocklist支持“类名/正则 + 自定义提示”的元组形式，你可以借助规则meta对象的message属性给出更有上下文价值的提示：

export default defineConfig({ blocklist: [ ['bg-red-500', { message: 'Use bg-red-600 instead' }], [/-auto$/, { message: s => `Use ${s.replace(/-auto$/, '-a')} instead` }], // -> "my-auto" is in blocklist: Use "my-a" instead ], })

规则实现见 rules/blocklist.ts 及其测试 blocklist.test.ts。

4.4enforce-class-compile：配合 compile-class 的前缀强制（可选）

该规则设计为与 compile class transformer 配合使用：当类属性或指令不是以:uno:开头时抛出警告或错误；同时该规则带有 wrench（--fix）能力，--fix时会自动给所有 class 属性与指令补上:uno:前缀。

选项（默认值来自 rules/enforce-class-compile.ts 的 schema 与defaultOptions）：

• prefix(string) —— 可与 transformer-compile-class 的自定义前缀 组合使用。默认：:uno:
• enableFix(boolean) —— 设为false时可仅提示不修复，适合渐进式迁移。默认：true

源码中的默认值：

defaultOptions: [{ prefix: ':uno:', enableFix: true }],

注意：当前仅支持 Vue。源码中JSXAttribute与SvelteAttribute的访问器目前是todo: add support | NEED HELP占位（见 rules/enforce-class-compile.ts）。如果你需要 Svelte 场景下的同类能力，可以关注 svelte-scoped 模式；欢迎以 PR 形式为 JSX 场景贡献支持。

五、如何开启可选规则

blocklist与enforce-class-compile默认不启用。在配置中显式声明即可：

Flat Config（eslint.config.js）：

import unocss from '@unocss/eslint-config/flat' export default [ unocss, { rules: { 'unocss/<rule-name>': 'warn', // or "error", 'unocss/<another-rule-name>': ['warn' /* or "error" */, { /* options */ }], }, }, ]

Legacy.eslintrc：

{ "extends": [ "@unocss" ], "rules": { "@unocss/<rule-name>": "warn", // or "error", "@unocss/<another-rule-name>": ["warn" /* or "error" */, { /* options */ }] } }

例如开启 blocklist 并让enforce-class-compile先只警告不自动修复：

{ rules: { 'unocss/blocklist': 'error', 'unocss/enforce-class-compile': ['warn', { prefix: ':uno:', enableFix: false }], }, }

六、与 UnoCSS 配置的联动：settings.unocss.configPath

一个容易被忽略的细节：order规则在检查时通过context.settings.unocss?.configPath读取 UnoCSS 配置文件路径（见 rules/order.ts），排序操作经由 worker 走真实的 UnoCSS 解析流程完成。这意味着规则结果会跟随你的 preset、shortcut、transformer 等配置变化——这也是为什么在 fixture 目录中同时提供了 uno.config.ts 与 eslint.config.ts 成对存在的测试夹具。若未显式配置settings.unocss.configPath，规则将按默认路径约定解析项目配置，跨目录 monorepo 场景建议显式指定。

七、致谢（Prior Art）

UnoCSS 的 ESLint 插件开发参考并感谢社区项目eslint-plugin-unocss（作者 @devunt），官方集成在其思路基础上演进为当前@unocss/eslint-plugin+@unocss/eslint-config的形态。

八、小结

如需查看完整实现，可从 plugin.ts（规则注册）、configs/flat.ts（Flat 默认配置）与packages-integrations/eslint-plugin/src/rules/目录下的各规则文件入手。

【免费下载链接】unocssThe instant on-demand atomic CSS engine.项目地址: https://gitcode.com/GitHub_Trending/un/unocss