CSS 变量校验实战：批量给一堆自定义属性做合法性检查

一个有点规模的设计系统，光颜色、间距、字号、阴影摊开就是几百个 CSS 自定义属性。它们散落在 tokens 文件、构建产物样式表、Figma 导出的清单里。问题是：人眼根本扫不出哪个名字漏了开头的 --，哪个夹了空格或中文逗号，哪个声明了却忘了填值。等到样式不生效再回头排查，已经浪费半天。

批量校验就是把这堆名字一次性喂进解析器，逐行核对合法性，再把"哪行错、错在哪"原样打印出来。下面说清楚校验的是哪几条规则、一个真实的对错例子，以及我自己用它清理 token 表的体感。

CSS 变量到底什么样才算合法

一个合法的自定义属性，名字必须以两个连字符 -- 开头，后面跟的标识符部分只能用字母、数字、下划线、连字符，以及 U+00A0 以上的 Unicode 字符。换句话说，--color-primary、--space-4、--z_modal 都没问题；而 -color（只有一个横线）、--1color 这种把数字放在紧贴双横线之后再混入非法结构的写法、--my color（中间有空格）、--主色：（夹了全角冒号）就过不了关。

值这一侧也要看：--radius: 后面空着、或者写成一段明显坏掉的内容，同样算无效。校验器把这两类问题分开报告，让你知道是名字的锅还是值的锅。

一个对错并排的真实例子

把下面这几行粘进 CSS 变量列表校验器：

--color-primary: #2563eb;
--1color: #ef4444;
--space-4: 16px;
--my radius:

输出（CSV 视图，每行带原因）大致是这样：

value,normalized,line,valid,reason
--color-primary,--color-primary,1,true,OK
--1color,--1color,2,false,名字不符合 CSS 标识符规则
--space-4,--space-4,3,true,OK
--my radius,--my radius,4,false,名称含非法字符且缺少有效值

--color-primary 这种规规矩矩的过；--1color 因为标识符部分起手就不合规被标红；带空格又空值的 --my radius 一次报两个问题。第一列保留你贴进来的原文，第三列保留行号，错了能立刻跳回原始文件那一行去改，不用靠肉眼数。

设计系统规范检查能拦住什么

团队协作时，token 是好几个人往里塞的。常见的翻车是：有人复制粘贴时把全角符号带进来，有人手抖把 --btn-bg 写成 --btn_bg 又写成 --btnBg，命名风格三套并存。批量校验先把硬性非法的揪出来，剩下的命名不一致问题，可以接着用规范化统一格式，再去重。

它还能按规范化结果排序、只保留唯一行、把无效项单独带出来复核。我习惯先勾上"包含无效项"，因为校验的目的就是看错误，把错的藏起来反而本末倒置。

我清一份 token 表的实际过程

上次接手一个三年没人系统整理的主题文件，我把里面所有自定义属性抠出来，约 280 行，直接整段粘进校验器。三秒不到，红了 9 行：6 个是早期手写时漏了第二个横线，2 个把冒号写成全角，还有 1 个值是空的占位没填。这 9 个里有 4 个一直导致暗色模式某个边框不显示，之前一直以为是层叠优先级问题，查了好几轮都没找对地方。

整个过程没有任何东西离开我的浏览器标签页。文件通过本地 File API 读取，解析、校验、导出全在前端跑完。给设计系统这种经常带内部命名、未发布配色的东西做检查，这一点我看得很重，毕竟不想把还没上线的 token 命名传到任何服务器上。

校验完导出 CSV 留底，带着行号和原因，相当于一份小型审计记录。下次有人再往文件里塞奇怪的属性，跑一遍就知道是谁、在哪行、错在哪。

---

Made by Toolora · Updated 2026-06-13