CSS 变量规范化:把混乱的自定义属性归一成统一命名

一个项目跑了两年,接手过三拨人,主题文件里的 CSS 自定义属性大概率长这样:有人写 --mainColor,有人写 --main-color,还有人写 --MAIN_COLOR。值也乱,同一个间距有人写 8px,有人写 0.5rem,有人干脆塞了个 8 px 中间带空格。这些变量散在十几个文件里,谁也不敢动,因为不知道改一个会牵连到哪。

这就是 CSS 变量需要规范化的时刻:把一批命名风格不一的自定义属性,批量统一成同一种约定,顺手把值格式和排序也理顺。

为什么团队的 CSS 变量会越写越乱

CSS 自定义属性没有强制的命名约束,这是它灵活的地方,也是它失控的根源。--Foo-Bar,--fooBar,--foo_bar 在语法上都合法,浏览器照单全收。于是每个人按自己的习惯写,代码评审又很难为命名风格卡一条线,半年下来变量表就成了大杂烩。

更麻烦的是这种混乱不报错。它不会让构建失败,不会让页面崩,只是悄悄拖慢每一次维护:搜索 --main-color 找不到 --mainColor 的引用,自动补全列出五种相似的名字,新人不知道该复用哪个,于是又新建一个。

kebab-case 统一:一种约定胜过五种

规范化的第一步,是把命名收敛到一种约定。CSS 社区和主流设计系统的事实标准是 kebab-case,也就是全小写加连字符:--main-color,--space-md,--font-size-lg。它和 CSS 属性本身的写法一致,读起来顺,也不会和 JavaScript 里的驼峰变量混淆。

统一命名要做三件事:

大小写归一,把 --mainColor 和 --MAIN_COLOR 都改写成 --main-color。
分隔符归一,驼峰的大小写边界和下划线 _ 都转成连字符 -。
前缀补全,漏掉开头 -- 的写法补上,多余空白去掉,保证每行都是一个能直接粘贴的干净变量名。

值格式统一:别让同一个数字有三种写法

命名理顺了,值也要顺。设计系统里最常见的不一致是间距和尺寸:8px 和 0.5rem 指向同一个视觉效果,却是两个字符串,搜索,替换,做 token 校验时全得当成两个东西处理。规范化时把值的空白,单位写法,大小写一并统一,后面无论是导出成 JSON token 还是塞进 SQL 过滤,都是一致的格式。

一个真实的输入输出例子

我自己接手一个旧后台的主题文件时,把翻出来的变量直接粘进规范化工具,输入是这样一坨:

--mainColor: #3366FF;
  --Main_Bg : #FFFFFF ;
--space-SM:8PX
mainColor: #3366ff

跑一遍规范化,排序加去重之后,输出干净成这样:

--main-bg: #ffffff
--main-color: #3366ff
--space-sm: 8px

命名全部归一成 kebab-case,多余空白去掉,十六进制色值统一成小写,重复的 --main-color 合并成一行,最后按字母排序。原本四行各写各的,现在三行规整可交接。第四行那个漏了开头 -- 的 mainColor 也被识别并补全,而不是被当成无法解析的脏数据丢掉。

规范化 ≠ 真实性校验

这里要提醒一句:规范化只保证格式干净,不保证语义正确。--space-md: 8px 命名再标准,也不代表它真的对应你设计稿里的中号间距。从网页或别人代码里复制来的文本常带隐藏空白,导入前先规范化再去重,能避开一批看不见的坑。如果要留审计线索,建议导出带行号的 CSV 或 Markdown,而不是只复制最终列表。

本地处理,源码不出浏览器

主题文件,内部 token,半成品分支里的变量,往往是还没公开的设计资产。CSS 变量规范化工具的解析,校验,去重,排序,导出全部在浏览器本地完成,上传的文本文件通过 File API 在当前标签页读取,不会发到服务器。你可以放心把整份主题文件拖进去整理。

如果你的需求只是从一坨 CSS 里先把自定义属性抽出来,可以先用 CSS 变量提取工具拿到原始列表,再回到规范化工具统一命名和值格式。两步配合,从乱到齐只要几分钟。

把命名约定写进文档当然好,但文档管不住手滑。规范化这一步,是在变量真正进入设计系统之前,给它加一道格式闸门。

Made by Toolora · Updated 2026-06-13