我所理解的 UnoCSS 最佳实践(5):Wind3 与 Wind4 的区别与迁移
- 为什么选择 UnoCSS
- CSS 如何减少重复
- 语义类名与工具类的工程实践
- Tailwind CSS 与 UnoCSS 的兼容边界
- Wind3 与 Wind4 的区别与迁移(当前)
- 工具类、任意值与任意属性怎么选
- 利用 Lint 规范写法
把 presetWind3() 换成 presetWind4(),构建通过了,页面却可能少了背景色,间距也可能失效。问题通常不在类名是否相似,而在这些类名背后的默认值、主题变量和初始化规则发生了变化。
Wind3 和 Wind4 是 UnoCSS 的两套预设。选择它们,决定的是工具类的规则与默认样式体系;从一套迁到另一套,需要同时核对配置、生成声明和页面里的依赖。本篇先解释两套预设的区别,再讨论迁移中容易遗漏的几个位置。
以下机制样本基于 UnoCSS 66.11.0 / 66.12.0 与 Chromium 156。Tailwind 与 UnoCSS 的跨工具差异、固定词汇查询和 apply 编译边界,见《Tailwind CSS 与 UnoCSS 的兼容边界》;这里集中讨论 UnoCSS 内部的预设选择与迁移。
Wind3 和 Wind4 是什么
UnoCSS 引擎负责解析候选工具类并生成 CSS,预设为它提供规则、变体、主题和预置样式。Wind3 / Wind4 里的数字描述所参考的 Tailwind 风格体系,两套预设都可以运行在 UnoCSS 66.x 上。
Wind3 参考 Tailwind CSS v3 / Windi CSS,旧的 presetUno、presetWind 已改名为 Wind3。Wind4 面向 Tailwind CSS v4 的能力与默认体系,同时保留许多 UnoCSS 扩展。它仍然使用 UnoCSS 的配置和生成机制;Tailwind v4 的 @theme、@utility、@reference 等编译指令需要另外辨认,不能直接照搬。
| 比较项 | Wind3 | Wind4 |
|---|---|---|
| 参考体系 | Tailwind v3 / Windi CSS | Tailwind v4,加上 UnoCSS 扩展 |
| 通用 reset | 通常另行引入 | 默认内置,可以关闭 |
| 主题键示例 | fontFamily、borderRadius、breakpoints |
font、radius、breakpoint |
| 生成声明 | 以具体规则为准 | 更广泛使用主题变量、逻辑属性、现代颜色与 @property |
UnoCSS 的 官方预设还包括精简的 Mini,以及 Icons、Typography 和 Attributify。后几种常与基础预设一起用,分别提供图标规则、排版样式和属性式写法。现代浏览器项目可以用 Wind4 打底,再按需补这些能力。
Transformer、extractor 和 processor 会一起带上吗
文档导航中列出的扩展有各自的启用入口。选择 Wind4 后,仍要区分哪些由引擎提供、哪些由预设带入、哪些需要主动配置:
| 机制 | 职责 | Wind3 / Wind4 的默认情况(66.12.0) |
|---|---|---|
| Transformer | 改写源码,例如展开 apply、改写模板分组 | 均未默认配置;apply 需要启用 directives |
| Extractor | 从源码提取候选工具类 | 引擎有默认 splitter;两套预设还包含 arbitrary-variants extractor |
| Processor | 继续处理 UnoCSS 生成的 CSS 层 | 均未默认配置;降级、压缩等能力按需添加 |
模板里的 hover:(...) 需要 variant-group transformer,Pug、MDC 等输入有各自的 extractor。Processor 处理的是生成层。业务 CSS 里的声明,或 directives 内联回选择器的声明,是否经过 processor,仍要对照项目的实际配置。
默认值和声明有哪些变化
相同的类名可以少改一处源码。迁移时仍要对照两个预设的默认主题、实际 CSS 属性及各自支持的工具类范围。
默认主题与 reset
下面是默认主题中的两个例子;圆角计算假定相关 rem 为 16px,ring 也没有另行指定颜色或宽度:
| 工具类 | Wind3 | Wind4 |
|---|---|---|
rounded-sm |
2px | 4px |
ring |
3px,默认蓝色 | 1px,默认 currentColor |
阴影、色板等默认值也需要比较。已有设计 token 时,显式保留它们通常比逐页接受新默认值更容易控制迁移范围。四组工具的浏览器对照与 CSS 记录,见兼容边界中的同名语义差异。
Wind4 默认带通用 reset。已有 reset 或组件基础样式时,可以只关闭这一部分:
presetWind4({
preflights: { reset: false },
});
关闭 reset 后,主题变量和内部初始化仍有用途。例如间距声明可能引用 --spacing,颜色可能引用 --colors-white,边框、阴影和变换还依赖内部变量。为了保留原来的基础样式而关闭所有 preflight,会连同这些依赖一起去掉。
物理方向、逻辑方向与断点单位
Wind3 的 px-20px py-16px 展开为四个物理方向的 padding,Wind4 使用 padding-inline / padding-block。常见水平书写模式中,两者可能得到相同布局;切到垂直书写后,inline 与 block 对应的方向就不同了。
min-h-0 等声明也可能改成引用主题变量的表达式。这些变化要结合消费环境判断:变量完整时可以得到相同结果,变量缺失时则可能使整条声明无效。声明字符串不同只是检查线索,属性重排本身不等于视觉回归。
Wind4 默认断点使用 40 / 48 / 64 / 80 / 96rem。已有 px 断点时,可以在迁移主题键后保留原条件,例如:
const config = {
theme: {
breakpoint: {
sm: '640px',
md: '768px',
lg: '1024px',
xl: '1280px',
'2xl': '1536px',
},
},
};
是否改用 rem,应由响应式设计决定。媒体查询里的 rem 与浏览器初始字号有关,不能只读取页面当前的根字号,再把 px / rem 机械换算成等价条件。
支持范围与目标浏览器
Wind4 增加了面向新体系的能力,也存在需要逐项核对的差异。例如在 UnoCSS 66.12.0 的默认配置下,Wind3 能生成 contain-inline-size,Wind4 未生成。预设数字更大,不代表旧输入全部被覆盖;固定词汇可以继续查四组兼容性查询页。
Wind4 会使用 @property、oklch、color-mix 和原生嵌套等现代 CSS 能力。先按 Wind4 的兼容性说明核对目标浏览器。还需要支持旧浏览器时,可以保留 Wind3,或为实际产物设计并验证兼容链路。
配置怎样迁移
面向现代浏览器的新项目,我会优先选择 Wind4。已有 Wind3 项目则先固定 UnoCSS 版本,保存当前配置和构建产物,再单独切换预设;这样更容易区分预设变化与依赖升级的影响。
对模板保留语义 class、只在样式层使用 apply,并且已有基础样式的项目,可以使用下面的配置:
import { defineConfig, presetWind4, transformerDirectives } from 'unocss';
export default defineConfig({
content: { pipeline: false },
presets: [presetWind4({ preflights: { reset: false } })],
transformers: [transformerDirectives()],
});
content.pipeline: false 关闭构建管线的内容提取,directives 仍会解析 apply。模板需要工具类时,保留相应的内容提取;需要默认 reset 的新页面,也可以保留 Wind4 的默认值。
主题对象要按 Wind4 主题迁移说明调整。常见的键名变化包括:
| Wind3 | Wind4 |
|---|---|
fontFamily |
font |
borderRadius |
radius |
breakpoints |
breakpoint |
boxShadow |
shadow |
easing |
ease |
字号、行高和尺寸等结构也有调整,需要按实际使用的主题项逐个确认。配置文件能加载,只说明语法被接受;覆盖项有没有参与生成,要继续看产物。
迁移时容易遗漏的问题
预设配置只是入口。真正消费 CSS 的文档、构建入口和 Shadow Root,分别决定依赖能否被解析。下面几类问题都可能在构建成功、交互测试通过后继续存在。
apply 消失了,不代表每个工具类都生效
未知项与合法 utility 混写时,directives 可能展开合法部分、过滤未知部分,最终不再残留 apply。只搜索产物里有没有 @apply,发现不了这种缺失。
迁移前应读取实际配置,展开分组并逐项检查 rules、shortcuts、variants 与 blocklist。下面几个实际输入在检查时未被识别,它们在原预设下就有问题:
| 原输入 | 原因 | 明确表达 |
|---|---|---|
muted |
普通 CSS class 不会自动注册成 utility | 引用对应主题色时使用 text-$muted |
transition-[background,border-color] |
本次两套预设均未生成对应规则 | [transition-property:background,border-color] |
overflow-wrap-anywhere |
当前规则不接受这个名字 | [overflow-wrap:anywhere] |
这些属于原有漏项,需要与迁移新增的回归分开判断。引擎接受新的表达后,还要让它经过真实预处理器。比如 Less 对带冒号、逗号的任意属性可能先报解析错误,可以使用整组 quoted apply:
.control
{
@apply 'border border-solid [transition-property:border-color,background] duration-120';
}
引擎生成与 Less 解析是两次检查。Vue CSS v-bind() 等框架编译还有自己的阶段要求,详见《Vite 插件顺序:从 CSS v-bind() 失效说起》。
声明已展开,主题依赖没有进入同一个入口
一个组件的 CSS 引用 --colors-white,变量定义却只由另一个构建入口提供,页面就可能回到继承色。客户端与 SSR 分别构建时尤其容易出现:只在服务端模块图中出现的组件,不能依赖客户端扫描恰好收集到相同的主题变量。
需要分别核对两份模块图消费的 CSS。客户端与服务端分别构建时,要确认各自需要的 UnoCSS 样式都进入了最终文档。同一次 Vite 构建中的多个 HTML 页面,则可以通过共享模块加载同一份样式。
自定义 Sass → PostCSS 链路也有相同边界。只有 apply 时,转换后的声明可能引用 --spacing,却没有输出它的定义。主页面另一份全局样式恰好补上变量,会掩盖独立使用时的问题。可以在 Sass 已输出的 CSS 前加入 PostCSS 占位符:
import postcss from 'postcss';
import UnoCSS from '@unocss/postcss';
import { presetWind4 } from 'unocss';
const plugins = [
UnoCSS({
configOrPath: {
presets: [presetWind4({ preflights: { reset: false } })],
content: { filesystem: [] },
},
}),
];
// compiledCss 是 Sass 已生成的 CSS。
const result = await postcss(plugins).process('@unocss;\n' + compiledCss, {
from: undefined,
});
这条链路只处理当前的 apply,用 filesystem: [] 可以避免占位符触发默认文件扫描。从模板提取 utility 时,再提供对应的内容来源。PostCSS 的 @unocss 占位符负责输出依赖层,apply 则把声明放回原选择器。
验证时,把每份 CSS 分别放到独立文档里,再检查变量解析后的 padding、颜色等结果。保留一个「只有 apply」的失败对照,比在主站全局样式全部加载后检查更容易暴露依赖缺失。
多页面共用一个 virtual:uno.css 入口
把模板原子类搬进 @apply 后,浏览器仍要解析展开后的 CSS。以 Wind4 的 @apply 'bg-white gap-0' 为例,背景引用 --colors-white,间距展开为 gap: calc(var(--spacing) * 0)。即使乘数为 0,浏览器也要先找到 --spacing。UnoCSS 的 Vite 集成通过 virtual:uno.css 提供这些主题变量和所需的初始化样式。content.pipeline: false 只关闭构建管线里的内容提取,组件仍依赖这些变量。
浏览器扩展下载站有两个独立 HTML 入口,分别是正式下载页和用于比较布局风格的试衣间。站点已经关闭模板提取和 Wind4 reset。用 UnoCSS 66.11.0 与 Vite 8.3.4 分别构建三种写法,再用 Chromium 在 1440px 和 390px 宽度下比较两页的计算样式。
| 写法 | 浏览器与构建结果 |
|---|---|
两个页面入口各自导入 virtual:uno.css |
两页加载同一份样式,UnoCSS 提示复用先解析到的虚拟模块。 |
| 两个入口都删除导入 | 根节点缺少 --spacing,试衣间的白色顶栏变透明,下载页窄屏工具栏的 gap 从 0px 变成 normal。 |
| 两个页面通过同一个模块导入 | 两个 HTML 都引用生成的共享样式文件。所采样的计算样式与原构建一致,重复导入提示消失。 |
共享模块只负责导入 UnoCSS,两个页面的挂载代码和页面专属样式仍放在各自的入口。以下是三个文件与 UnoCSS 有关的部分。
// src/uno-styles.ts
import 'virtual:uno.css';
// src/main.ts
import './uno-styles';
// src/style-lab/main.ts
import '../uno-styles';
Vite 从两个 HTML 入口都能沿着依赖找到 uno-styles.ts,而 UnoCSS 的虚拟模块只有这一处直接导入。判断能否移除公共样式时,可以先看组件 CSS 是否引用了主题变量或初始化属性,再把两个生产 HTML 分别打开,核对背景、间距和响应式状态的计算值。
Shadow Root 中的初始化缺失
Shadow UI 可能仍能点击、切换状态,背景和边框却已经失效。在本次 Chromium 156 的样本中,Shadow Root 没有获得与文档样式相同的 @property 初值,默认带支持条件的初始化也没有补上相应内部变量,面板背景最终绘制为透明色。
对这一类入口,可以显式输出初始化:
presetWind4({
preflights: {
reset: false,
property: { parent: false },
},
});
Wind4 的 parent: false 设置会去掉初始化规则外层的条件包装,保留 property 初始化层。先核对 Shadow Root 里的实际结果,普通文档可以继续使用默认配置。
背景断言在修复前读取到 [0, 0, 0, 0],修复后为 [255, 255, 255, 255];同时检查边框绘制为 solid。这个失败对照验证了视觉结果,也说明只检查按钮和状态更新无法覆盖样式回归。
颜色相同,序列化字符串不同
现代颜色经过混合后,浏览器可能返回 oklab 等形式。把白色固定断言成字符串 rgb(255, 255, 255),会将格式变化误判为视觉问题。
需要验证不透明白色时,可以用 Canvas 读取 8 位 RGBA,继续拒绝透明色与错误颜色。它适合这里的背景检查;涉及广色域、精度或完整色彩管理时,需要更严格的验证口径。
怎样确认迁移完成
先保存原配置与构建基线,再逐项检查工具类能否被实际配置识别。接下来比较生成声明、主题变量与初始化层,最后让各入口独立进入浏览器,检查背景、边框、间距、主题、响应式临界点和交互。
页面对照应固定 DOM、字体、主题 token、视口和动画状态。进入动画的中间帧、外部字体加载时机,都可能改变截图;声明重排和现代颜色序列化也不能直接计作视觉回归。旧版本实验与测试 fixture 继续保留原预设,避免改写历史结果的含义。
本文中的 PostCSS 与 Shadow Root 失败对照见迁移检查样本弹窗。它们确认的是指定版本和环境下的依赖、初始化与绘制行为,其他目标浏览器仍需分别验收。
迁移 Wind4 时,逐个检查消费入口是否加载了生成样式、主题变量和所需的初始化规则。入口能构建只是第一步,还要在页面验证背景色、间距和其他依赖这些规则的样式。
上一篇:Tailwind CSS 与 UnoCSS 的兼容边界。
预设迁移的依赖与初始化检查
记录固定 UnoCSS 66.11.0 / 66.12.0 与 Chromium 156.0.8078.4 下的机制样本:未识别工具类、PostCSS 输出占位符与 Shadow Root 内部变量初始化。
PostCSS 检查保留只有 apply 的失败条件,再加入 @unocss 验证独立文档中的依赖;Shadow Root 检查保留默认初始化条件下的透明背景,再验证显式初始化后的不透明白色与 solid 边框。测试必须能在修复前失败,才能证明断言覆盖到了问题。
这些记录不构成全部工具类或浏览器的支持矩阵,也不证明所有页面逐像素等价。
固定版本下的失败与修复结果
{
"date": "2026-11-02",
"browser": "Chromium 156.0.8078.4",
"unocssVersions": [
"66.11.0",
"66.12.0"
],
"scope": "固定版本下的工具类识别、PostCSS 依赖输出与 Shadow Root 初始化样本。",
"initialUnrecognizedTokens": [
"muted",
"transition-[background,border-color]",
"transition-[border-color,background,opacity]",
"overflow-wrap-anywhere",
"transition-[color,border-color,background,outline-color]",
"transition-[border-color,background]"
],
"negativeControls": [
{
"case": "PostCSS 只有 apply",
"result": "声明引用 --spacing,未输出定义;加入 @unocss 后独立文档正常。"
},
{
"case": "Shadow Root 沿用默认内部变量初始化条件",
"actualBackground": [
0,
0,
0,
0
],
"expectedBackground": [
255,
255,
255,
255
],
"result": "新断言在修复前失败;property.parent:false 后背景和 solid 边框通过。"
}
],
"limitations": [
"工具类名单是实际输入样本,不代表所有动态规则或自定义配置。",
"浏览器结果限 Chromium 156,未据此证明 Safari、Firefox 或旧浏览器行为。",
"背景绘制按 8 位 RGBA 验证,不构成高精度色彩或全部页面逐像素等价证明。"
]
}