CSS 变量批量转换：从键值对到设计令牌的完整路子

做主题系统的时候，最磨人的不是写样式，是搬数据。设计师交来一张 Figma 令牌表，里面是 brand-primary: #2563eb 这样几十上百行键值对，你要把它们逐个改写成 --brand-primary: #2563eb;，再有人要 SCSS 变量版本，又有人要一份 JS 对象塞进组件库。手改容易漏逗号、漏分号，复制粘贴还会带进隐藏空白。这件事本该是机器干的。

CSS 变量列表转换器 就是为这个交接环节写的：粘一堆文本进去，解析、去重、排序、换格式，全程在浏览器本地完成，输出就是能直接交付的产物。

键值对到底怎么变成 --name:value

CSS 自定义属性的写法很固定：--变量名: 值;，必须以两个连字符开头，挂在某个选择器作用域里，通常是 :root。所以转换的核心就是把每一行的「键」补上 -- 前缀，把「值」原样接在冒号后面，再补上分号。

举个具体的。你有这样一组颜色键值对：

brand-primary = #2563eb
brand-secondary = #7c3aed
text-base = #1f2937
surface = #f9fafb

转成 CSS 自定义属性，结果是：

:root {
  --brand-primary: #2563eb;
  --brand-secondary: #7c3aed;
  --text-base: #1f2937;
  --surface: #f9fafb;
}

要 SCSS 变量版本，同一批数据换个输出格式就行：

$brand-primary: #2563eb;
$brand-secondary: #7c3aed;
$text-base: #1f2937;
$surface: #f9fafb;

要喂给前端组件库，导成 JS 对象 / JSON 也是同一个解析器的事：

{
  "brand-primary": "#2563eb",
  "brand-secondary": "#7c3aed",
  "text-base": "#1f2937",
  "surface": "#f9fafb"
}

一份源数据，三种交付形态，省掉的就是来回手敲引号和分号的时间。

设计令牌迁移：一次清洗，多处复用

设计令牌的价值在于「单一来源」。颜色、间距、圆角、字号集中管理，主题切换才不会到处漏改。但迁移阶段往往很乱：旧项目里的色值散在各个组件，新的令牌表又是从表格导出的。把这些来源都粘进转换器，先去重，再按规范化结果排序，一眼就能看出哪些是重复定义、哪些命名对不上。

我自己上次给一套后台换深色模式，手里有三份来源：现有的 SCSS 文件、设计师的新色板、还有一份 CSV 导出。三份合并后有四十多行，肉眼根本数不清重复。粘进去去重排序后，剩下二十八个唯一令牌，重复的十几行一目了然。那一步省下的对账时间，比我预想的多得多。

命名规范别等到最后才管

批量转换最容易暴露命名问题。brandPrimary、brand-primary、brand_primary 混在一起，机器看就是三个不同的键。CSS 自定义属性区分大小写，--Brand 和 --brand 是两个变量，这点尤其要小心。

建议在转换前就统一规范：CSS 变量普遍用小写加连字符（kebab-case），语义化命名优于具体值命名，也就是写 --color-danger 而不是 --color-red，将来红色想换成橙色不用满项目改名。转换器会把无效项单独带出来并附上原因，值为空或名字写坏的行不会被悄悄丢掉，方便你回到源文件修好再生成最终产物。

本地处理，敏感数据不出浏览器

令牌表里有时会混进内部标识符或带 token 的注释。这个工具所有解析、校验、去重、复制、下载都在浏览器本地跑，上传的文本文件通过 File API 在当前标签页读取，不发往服务器。如果某些值需要进一步整理格式，可以接着用 CSS 变量规范化工具 把空白、大小写和写法统一掉，再回到转换器导出最终格式。

什么时候用它最划算

不是所有场景都需要批量转换。三五个变量手写更快。但只要数量过了二十行，或者要同时产出 CSS、SCSS、JSON 多种格式，或者要把多份来源合并去重，机器就比手工稳得多，也不会在深夜赶版本时漏掉一个分号。设计令牌系统越大，这种确定性越值钱。

---

Made by Toolora · Updated 2026-06-13