UnoCSS Processors 完整指南：在 CSS 生成后精加工每一层样式

UnoCSS Processors 完整指南：在 CSS 生成后精加工每一层样式

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

Processors（处理器）是 UnoCSS 提供的一组钩子（hook），用于在 CSS 生成完成之后、对外暴露之前对每一层（layer）的样式进行二次加工。与在提取前改写源码的 Transformers 不同，Processors 直接作用于已生成的 CSS 文本，可用于添加 banner 注释、压缩、做浏览器兼容转换等场景。读完本文，你将掌握 Processor 的定义方式、执行流程、排序规则与上下文信息，并能基于仓库源码理解其底层实现，从而编写出可复用的自定义处理器。

Processors 与 Transformers：两个阶段，两种职责

UnoCSS 的整个流水线可以分为两个截然不同的阶段，Processors 和 Transformers 分别作用于其中：

• Transformers（转换器）：在源码提取之前修改源代码。例如transformer-variant-group会把hover:(bg-red-500 text-white)这类分组写法展开为标准工具类。它们处理的是"还没被识别"的源码文本，详见 docs/config/transformers.md。
• Processors（处理器）：在UnoCSS 生成完 CSS 层之后运行。它们接收某一层已经生成好的 CSS 字符串，返回要替换它的新 CSS 字符串。它们处理的是"已经生成"的 CSS 产物。

两者的定位差异决定了 Processors 非常适合做任何"面向最终 CSS 产物"的工作，比如：

• 给生产构建的 CSS 追加版本注释或版权 banner；
• 对生成的 CSS 做 minify（压缩）；
• 将现代 CSS 语法编译为指定浏览器目标支持的语法；
• 统一调整某些层级的输出格式。

定义一个 Processor

在类型层面，一个 Processor 就是一个实现了CSSProcessor接口的对象。其定义位于 packages-engine/core/src/types.ts#L860-L864：

export interface CSSProcessor<Theme extends object = object> { name: string order?: number process: (css: string, context: CSSProcessorContext<Theme>) => Awaitable<string> }

三个字段的含义：

• name：处理器名称，必填。它用于在合并配置时去重（详见下文"处理器合并"小节）；
• order：可选，处理器执行顺序，数值越小越先执行，缺省按0处理；
• process：核心方法，接收当前层的 CSS 字符串与上下文，返回替换后的 CSS。返回值可以是同步字符串，也支持Promise<string>（异步处理器）。

官方文档给出一个"添加 banner"的完整示例，在uno.config.ts中注册：

import type { CSSProcessor } from '@unocss/core' import { defineConfig } from 'unocss' const banner: CSSProcessor = { name: 'add-banner', order: 10, process(css, { layer, envMode }) { if (envMode !== 'build') return css return `/* generated layer: ${layer} */\n${css}` }, } export default defineConfig({ processors: [banner], })

这个示例同时演示了两个实用点：

1. 按环境区分行为：通过envMode判断当前是开发模式还是生产构建，只在build时插入 banner，避免开发调试时 CSS 被额外注释干扰；
2. 按层区分行为：通过layer拿到当前处理的是哪一层，可以针对特定层做差异化处理。

处理流程：每一层 CSS 如何被加工

对于每一个非空的 CSS 层，UnoCSS 会执行以下步骤：

1. 生成原始层 CSS：包括该层的 preflights、以及开启后包裹的 CSS 层包装器或层标记（例如/* layer: default */注释，或@layer xxx { ... }包装）；
2. 按order升序排序所有处理器；
3. 顺序串联执行：每个处理器依次接收上一处理器的输出作为输入，形成一条流水线；
4. 缓存处理结果：处理后的层被缓存，通过getLayer()、getLayers()和最终的css结果对外暴露。

这条流水线可以用下面的示意图表达：

generated layer -> processor 1 -> processor 2 -> processed layer output

源码层面的实现位于 packages-engine/core/src/generator.ts#L519-L530。processLayer函数先对处理器数组做一次slice().sort()（按order升序），然后用for...of循环把每个处理器的输出喂给下一个处理器：

const processors = this.config.processors?.slice().sort((a, b) => (a.order || 0) - (b.order || 0)) ?? [] const processLayer = async (css: string, layer: string) => { let processed = css const context: CSSProcessorContext<Theme> = { layer, theme: this.config.theme, envMode: this.config.envMode || 'build', } for (const processor of processors) processed = await processor.process(processed, context) return processed }

注意这里对order的判断是a.order || 0，这与文档中"未显式指定order的处理器使用0"的规则完全一致（见 packages-engine/core/src/generator.ts#L519）。

在实际的generate()调用中，所有层会通过Promise.all并行执行各自的processLayer（packages-engine/core/src/generator.ts#L559-L562）：

await Promise.all(layers.map(async (layer) => { const raw = getRawLayer(layer) processedLayerCache[layer] = raw ? await processLayer(raw, layer) : raw }))

这意味着不同的层可能被并发处理。因此官方文档特别提醒：处理器内部应避免依赖在层之间共享的可变状态，否则并发执行时可能出现竞态问题。

Context：处理器能拿到哪些信息

process()的第二个参数是CSSProcessorContext，其类型定义同样在 packages-engine/core/src/types.ts#L843-L858：

interface CSSProcessorContext<Theme extends object = object> { layer: string theme: Theme envMode: 'dev' | 'build' }

三个字段的含义与用途：

envMode的默认值在配置解析阶段被确定为'build'（见 packages-engine/core/src/config.ts#L232 的envMode: config.envMode || 'build'），也可以通过defineConfig显式指定。

关于层（layer）的更多背景，比如如何给规则设置层、如何控制层顺序、如何输出 CSS Cascade Layers，可以参考 docs/config/layers.md。

处理器顺序：order 决定执行次序

Processors 的排序规则非常简单：order越小越先执行，未指定order时默认为0。官方文档给出的示例：

processors: [ { name: 'minify', order: 20, process: minify }, { name: 'prefix', order: 10, process: addPrefixes }, ]

在这个例子中，prefix（order: 10）会先于minify（order: 20）执行，即先补前缀、再压缩。这一顺序在 packages-engine/core/src/generator.ts#L519 的sort((a, b) => (a.order || 0) - (b.order || 0))中得以落实。

设计自己的处理器时，合理分配order很关键：例如"先压缩再追加注释"和"先追加注释再压缩"的产物截然不同，请根据你的实际目标确定各处理器的相对顺序。

处理器合并：preset 与用户配置的去重规则

Preset（预设）和用户配置声明的 processors 会被合并在一起。合并逻辑在 packages-engine/core/src/config.ts#L254：

processors: uniqueBy(getMerged('processors'), (a, b) => a.name === b.name),

getMerged会将所有来源（presets + 用户配置）的processors扁平化合并（见 packages-engine/core/src/config.ts#L175-L177），随后uniqueBy依据name去重：同名处理器只保留一个。这正是CSSProcessor接口中name字段为必填的原因——它是处理器身份的唯一标识。

这一机制意味着：

• 如果你想覆盖某个 preset 自带的处理器，定义一个同名处理器即可替换掉它；
• 如果你定义了两个同名但不同实现的处理器，后者（按合并顺序）会取代前者，而不会重复执行；
• 给处理器起一个全局唯一、描述性强的名字（如'add-banner'、'@unocss/processor-lightningcss'）有助于避免意外的冲突与覆盖。

错误处理与 setLayer：重复处理防护

错误传播：如果某个处理器抛出异常，该层的生成将失败，错误会向上传递给generate()的调用方。从 packages-engine/core/src/generator.ts#L520-L530 可以看到，processLayer内部没有对单个处理器做 try/catch，任何await processor.process(...)抛出的错误都会沿 Promise 链向外传播。

setLayer 的重新处理：GenerateResult暴露了setLayer(layer, callback)接口，允许你在生成后修改某一层的内容（类型定义见 packages-engine/core/src/types.ts#L984）。它的实现位于 packages-engine/core/src/generator.ts#L551-L557：

const setLayer = async (layer: string, callback: (content: string) => Promise<string>) => { const raw = await callback(getRawLayer(layer)) const processed = await processLayer(raw, layer) rawLayerCache[layer] = raw processedLayerCache[layer] = processed return processed }

这里有一个精心设计的细节：callback 接收到的是原始（未经处理）的 CSS（getRawLayer(layer)），而不是已经过处理器加工的输出。UnoCSS 随后会把 callback 返回的新 CSS从头到尾再完整跑一遍处理器链。这样设计是为了防止处理器被反复应用到它们自己的上一次输出上，从而避免"处理结果被二次处理"导致的重复压缩、重复加注释等问题。

官方处理器：Lightning CSS Processor

UnoCSS 官方提供了一款开箱即用的处理器——Lightning CSS processor（@unocss/processor-lightningcss），文档位于 docs/processors/lightningcss.md。它基于 Lightning CSS 对每个生成的层做压缩、现代语法编译和浏览器兼容转换。

安装：

pnpm add -D @unocss/processor-lightningcss # 或 npm install -D @unocss/processor-lightningcss / yarn add -D ...

在uno.config.ts中注册：

import processorLightningCSS from '@unocss/processor-lightningcss' import { defineConfig } from 'unocss' export default defineConfig({ processors: [ processorLightningCSS({ targets: { chrome: 111 << 16, safari: 15 << 16, }, }), ], })

其源码实现位于 packages-presets/processor-lightningcss/src/index.ts，核心逻辑值得展开看看：

process: async (css, { layer, envMode }) => { if (!getEnvFlags().isNode) { warnOnce('@unocss/processor-lightningcss is not supported in non-Node.js environments; returning CSS unchanged') return css } const result = transform({ code: Buffer.from(css), filename: `${layer ?? 'uno'}.css`, minify: envMode === 'build', ...options, }) return result.code.toString() }

几个值得注意的实现要点：

• Node.js only：它使用 Lightning CSS 的原生 Node.js 构建，专为构建期设计。当在非 Node.js 环境中被调用时，UnoCSS 会通过warnOnce发出一次警告并原样返回 CSS（warnOnce保证只警告一次，不会刷屏）。对应测试见 packages-presets/processor-lightningcss/test/index.test.ts#L54-L69。
• 以层名作为文件名：filename被设置为${layer ?? 'uno'}.css，例如utilities层会以utilities.css传给 Lightning CSS，使转换错误信息更易定位。测试 packages-presets/processor-lightningcss/test/index.test.ts#L22-L28 专门验证了这一点。
• minify 默认值与 envMode 联动：默认在envMode === 'build'时压缩、'dev'时不压缩；也可通过minify选项显式覆盖。
• targets：通过targets指定浏览器目标（如chrome: 111 << 16），控制 Lightning CSS 应用哪些兼容性转换。
• 处理器接受 Lightning CSS 的TransformOptions（除code和filename由 UnoCSS 自行提供外），层名会作为文件名传入。

测试 packages-presets/processor-lightningcss/test/index.test.ts#L30-L52 同时验证了"每个生成的层都会被处理，且setLayer后重新处理"这一完整行为：它构造了两个不同层的规则，生成后断言getLayer('a')与getLayer('b')均已被压缩，随后调用setLayer修改内容并验证处理器链被重新应用。

实战小结：何时使用 Processor

综合文档与源码，可以归纳出适合使用 Processor 的典型场景：

1. 给产物加元信息：如 banner、构建时间、版本注释；
2. CSS 后处理：压缩、去重、格式化；
3. 兼容性转换：面向特定浏览器目标编译现代 CSS 语法；
4. 产物审计：统计每层 CSS 大小、记录层名等。

而"改写源码以支持某种写法约定"这类需求，则应交给 Transformers（docs/config/transformers.md）处理。记住这一职责划分：Processors 改的是"生成的 CSS"，Transformers 改的是"输入的源码"。

编写自己的处理器时，最后再回顾四条核心准则：

• name必填且全局唯一，否则可能与 preset 中的处理器冲突；
• 用order控制执行次序，小心串联顺序对产物的影响；
• 不要依赖跨层的共享可变状态，因为不同层会被并发处理；
• 如需在生成后修改层内容，通过setLayer传入的 callback 拿到的是原始 CSS，修改后会自动重跑完整处理器链。

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