在学习 CSS 的过程中变量经常是被放得很靠后的知识点很多人一上来就刷选择器、盒模型、布局等到做项目的时候才被“改一个主题色要改十几个文件”这种事逼着回来补课。我属于后者。前阵子为了把一个后台系统的主题色从蓝色改成绿色我原以为就是全局搜索替换结果发现同一个蓝色在边框、阴影、渐变、hover 状态和 loading 动画里出现了十几种不重样的写法改到一半直接放弃。后来真正让这套样式变得可以维护的就是 CSS 变量CSS Variables。这篇文章我会从它解决什么问题开始把自定义属性的语法、继承机制、常见应用场景和坑都过一遍适合刚接触 CSS 变量的读者也希望给已经在项目里用变量的同学提供一些排查思路。1. 从主题色改造说起CSS 变量到底解决了什么1.1 一个调整主题色引发的连锁反应我原来的代码里#2563eb这个蓝色直接散落在几十个规则里。有的是background: #2563eb有的是border-color: #2563eb有的是box-shadow: 0 4px 12px rgba(37, 99, 235, 0.15)还有 hover 时要把颜色加深我不得不手动算一个#1d4ed8写下去。最难受的是渐变和透明度rgba(37, 99, 235, 0.1)这种写法在全局搜索里几乎没法直接替换因为 RGB 和透明度是拆开的。当时所有人给的方案都是“用编辑器的全局替换功能把所有 #2563eb 换成 #16a34a”。听起来合理实际上做不下去。替换完主色还有同色系的浅色背景、边框、分割线、hover 状态、选中状态这些颜色都不是同一个值而是同一个色相在不同透明度下的变体。你想统一改版需要先手工列一张“物理颜色值对照表”再逐个规则去核对。这种改动方式效率极低而且很容易漏掉某个角落的状态样式。那次之后我认真意识到一个问题大部分前端项目的样式维护成本不是来自“不会写 CSS”而是来自“没有一个地方能说清楚这些值到底是什么”。颜色值、间距值、圆角值散落在各个规则里它们之间的关系只能靠人脑记忆一旦要大规模调整就只能靠搜索替换碰运气。1.2 变量解决的是“一处定义多处引用”的问题CSS 变量的核心价值是把“值”从“使用位置”中抽离出来。品牌色不再是散落在每个按钮、标题、链接里的#2563eb而是定义在:root里的一个变量--color-primary。组件里写的是var(--color-primary)以后想换主题色只需要改这一个变量。这看起来非常基础但它的意义并不只是“减少重复”。它让 CSS 第一次有了像样的“设计令牌”机制。你可以把颜色、间距、字号、圆角、阴影这些基础层的东西全部集中管理然后在具体组件里只表达“我要用主色”“我要用小号间距”而不是反复书写具体的像素值和色号。这样组件本身的可读性会提升一大截新人接手时也不用猜某个#f8fafc是从哪来的。1.3 它是运行时的机制不是字符串替换很多人第一次接触 CSS 变量时会把它理解成“预处理器变量那种编译期替换”。实际上它们有本质区别。Sass/Less 的变量在编译阶段就会被展开成具体值编译之后的 CSS 文件里根本看不到变量这个概念。而 CSS 变量使用的是自定义属性它会真实存在于 DOM 树中可以继承、可以被新声明覆盖也可以被 JavaScript 直接读写。这个区别决定了 CSS 变量能做到很多预处理器变量做不到的事最典型的就是“运行时切换主题”。你在浏览器里改掉:root上的一个变量页面上所有引用了这个变量的元素会立刻更新不用改任何样式文件也不用重新构建。正因为它是属性不是宏才具备这种动态能力。2. 自定义属性语法--前缀、var() 和作用域继承2.1 声明一个变量没那么玄乎CSS 变量的正式名称是自定义属性声明方式就是在任何选择器里写一个以--开头的属性。:root { --brand-color: #2563eb; --space-md: 16px; --font-body: Inter, system-ui, sans-serif; }这里有两个细节需要注意。第一--前缀不能省略写成$brand-color或者brand-color都不对那是预处理器和旧语法的思路。第二自定义属性是大小写敏感的--Brand-Color和--brand-color是两个完全不同的变量这一点和普通 CSS 属性不同。变量值可以是任何合法的 CSS 值甚至可以是一整段带空格的复合值比如1px solid var(--brand-color)。只要不包含不合法的字符浏览器都会原样保存它直到被var()取用时才真正参与属性计算。2.2 var() 读取变量与回退值声明之后用var()函数来读取.button { background: var(--brand-color); padding: var(--space-md); }var()还可以接收第二个参数作为回退值.button { background: var(--brand-color, #2563eb); }当第一个参数对应的变量没有被定义时浏览器会使用第二个参数。这里有一个容易被误解的地方回退值只在“变量未定义”的时候生效。如果变量被定义了但是值在放到这个属性里之后是非法的比如把颜色值赋给了width浏览器不会使用回退值而是把该属性当成unset处理。这个坑我后面会展开讲。回退值里还能继续套var()实现多级回退.button { background: var(--btn-bg, var(--brand-color, #2563eb)); }这种写法在做主题系统时很实用因为可以做到“组件级变量优先全局变量兜底”。2.3 变量随 DOM 树继承也随级联覆盖自定义属性是普通属性所以它遵循 CSS 的级联和继承规则。定义在某个元素上这个元素的所有子元素都能访问如果子元素也声明了同名变量就会覆盖父级的值。:root { --accent: #2563eb; } .section-highlight { --accent: #dc2626; } .title { color: var(--accent); }.title如果放在.section-highlight内部会显示红色如果放在外面会显示蓝色。这其实就是 CSS 变量最强大的地方它不是一个全局常量表而是一个可以按 DOM 树逐层覆盖的变量环境。“在容器上改一个变量子树里所有相关组件整体变化”这个能力是后面所有主题切换方案的基础。2.4 可以直接抄的卡片组件示例用一个简单的卡片来演示完整语法div classcard style--radius: 16px h2卡片标题/h2 p这里是卡片内容继承容器上的变量。/p /div.card { --radius: 8px; --padding: 16px; background: var(--card-bg, #ffffff); border: 1px solid var(--card-border, #e5e7eb); border-radius: var(--radius); padding: var(--padding); transition: box-shadow 0.2s ease; } .card:hover { border-color: var(--brand-color, #2563eb); box-shadow: 0 4px 12px rgba(37, 99, 235, 0.15); }注意这里我把--radius同时定义在.card上又在某个实例上通过 inline style 覆盖成16px。由于内联样式优先级最高这个实例的圆角会变成 16px而其他卡片还是 8px。用这种方式组件不需要为每一种形态写一个 class只需要暴露几个变量就能让使用者按需调整。3. Sass/Less 变量与 CSS 变量两者为什么不是一回事3.1 编译期变量与运行时变量的差异很多项目里 Sass 和 CSS 变量是并存的有人就疑惑既然 Sass 已经有$color了为什么还要用 CSS 变量我把它们的差异拉了一张表维度Sass/Less 变量CSS 变量解析时间编译期运行时浏览器能否读取不能能JavaScript 修改无法可以setProperty编译后的产物替换后的静态值保留var()作用域依据嵌套块/文件DOM 树与级联能否响应媒体查询只能重新生成属性可以在媒体查询里换变量用一句话概括Sass 变量在部署之前就已经“消失”了CSS 变量在用户浏览器里还活着。3.2 作用域模型的本质差异Sass 变量的作用域是编写代码时的块级作用域比如在mixin里定义的$color只存在于这条 mixin 内部。这种作用域是静态的、编译期就固定好的。CSS 变量不同它的作用域是 DOM 树上的继承关系。同一个变量名在body上是一个值在某个.card容器里可以被覆盖成另一个值而这个覆盖只影响.card的所有子孙节点。这是一种运行时才真正生效的作用域机制。具体到场景上CSS 变量能做“组件级别的参数注入”Sass 变量想做同样的事要么靠 mixin 传参要么靠复制一整套样式复杂度和维护成本都会高不少。3.3 项目里怎样分工配合实际工程中两者不冲突反而能配合。Sass 适合处理需要生成重复规则的地方比如循环生成工具类、mixin 封装这些是编译期的工作。CSS 变量更适合承担运行时主题和设计令牌。$btn-padding: 12px 16px; .btn { padding: $btn-padding; color: var(--text-color, #ffffff); background: var(--btn-bg, #2563eb); }这种写法我比较推荐Sass 负责代码结构上的复用CSS 变量负责样式系统上的可变性。如果团队在用原子化 CSSCSS 变量还能作为工具类背后的设计令牌来源比如给原子类预设一组--spacing-*、--color-*既保持原子化的灵活又避免全项目到处散落魔法值。4. 动态主题切换从写死颜色到语义化令牌4.1 先定义语义层而不是直接用颜色值做主题切换时最容易犯的错是直接定义一堆物理色名比如--blue、--gray-100。这样切主题时你还是得改每个组件里到底引用了哪个物理色。正确做法是在物理色之上再加一层语义变量物理变量语义变量用途--blue-500: #2563eb--color-primary主按钮、链接、强调--gray-100: #f1f5f9--bg-subtle弱化背景--gray-900: #0f172a--text-body正文文字颜色--gray-400: #94a3b8--text-muted次要文字组件里只写var(--color-primary)不关心它背后是蓝色还是绿色。以后做白底、黑底、高对比度主题时只需要在全局重写语义变量组件代码完全不用动。4.2 深色模式不用重写一套 CSS深色模式是语义化变量最典型的收益场景:root { --bg-body: #ffffff; --bg-card: #f8fafc; --text-body: #1f2937; --border-subtle: #e5e7eb; } media (prefers-color-scheme: dark) { :root { --bg-body: #0f172a; --bg-card: #1e293b; --text-body: #f1f5f9; --border-subtle: #334155; } } body { background: var(--bg-body); color: var(--text-body); }你会发现整个黑暗模式的代码量只有几组变量覆盖其余所有组件样式都跟以前一样。这才是主题系统应该有的样子——不是各写一套样式而是同一套样式在不同变量环境下呈现不同外观。4.3 手动切换主题data-theme 与 JS setProperty跟随系统只是基础更多产品需要用户手动切主题。这时用>:root[data-themedark] { --bg-body: #0f172a; --bg-card: #1e293b; --text-body: #f1f5f9; --border-subtle: #334155; }JavaScript 只需要切换属性function setTheme(theme) { document.documentElement.setAttribute(data-theme, theme); localStorage.setItem(theme, theme); }如果是运行时收到服务端下发的某个动态色值也可以直接改变量const rootStyle document.documentElement.style; rootStyle.setProperty(--brand-color, #16a34a);这里我想强调一点有了 CSS 变量之后JS 和样式之间的通信成本极低。以前你要临时换一个颜色得在 JS 里操作一堆 DOM 元素的style.background现在只需要改一个变量整个页面的相关元素统一响应。4.4 防止首屏闪错的加载经验手动主题在刷新页面时容易闪一下因为你可能在 CSS 加载完之后才设置>script var theme localStorage.getItem(theme); if (theme) { document.documentElement.dataset.theme theme; } /script link relstylesheet hrefapp.css这样浏览器一解析html标签就已经带上了正确的主题属性后面的 CSS 规则直接命中不会先渲染成默认主题再跳变。这个细节看着小但做主题切换产品的人基本都踩过。5. 变量与 calc()、媒体查询、动画组合出高级玩法5.1 在媒体查询里换变量而不是换整套样式响应式设计里最常见的写法是每到一个断点就复制一遍规则、改一堆属性值。用 CSS 变量可以把这个过程改造成“只换变量”.grid { --gap: 24px; --columns: 3; display: grid; gap: var(--gap); grid-template-columns: repeat(var(--columns), 1fr); } media (max-width: 768px) { .grid { --gap: 12px; --columns: 2; } } media (max-width: 480px) { .grid { --columns: 1; } }.grid的布局规则从头到尾只写了一份断点里只改变量。新人在改响应式间距时不需要去翻那一大堆重复规则改起来心智负担小很多。5.2 calc() 里的空格、单位和嵌套变量CSS 变量经常和calc()一起用这也是坑最多的地方。:root { --gap: 8px; --scale: 2; } .item { margin: calc(var(--gap) 4px); padding: calc(var(--gap) * 2); width: calc(100% / var(--scale)); }先说空格calc()里加法运算符和减法运算符两侧必须有空格calc(100%-20px)是无效的。乘法除法目前现代浏览器也能用但为了兼容性更稳的项目我一般建议尽量用加减法必要时用纯数字变量配合乘法。再说单位不能通过字符串拼接的方式把变量变成带单位的值比如calc(var(--size)px)是错的。要把一个纯数字变量变成长度正确写法是calc(var(--size) * 1px)。如果变量已经带了单位比如--gap: 8px那就直接参与运算不要在后面再拼一个单位。还有一种情况是变量值本身包含空格导致整条规则失效。比如有人在变量声明后面加了注释:root { --offset: 8px /* 基础间距 */; } .box { margin: calc(var(--offset) 4px); }注释跟着变量值一起被解析最终计算出来的值可能会被判定为非法。这类问题非常隐蔽直接看代码看不出毛病只有把计算后的值打印出来才能发现。5.3 让变量动起来动画与交互反馈很多人以为 CSS 变量不能做动画因为普通变量参与transition时是离散跳变的。实际上浏览器只是不知道该怎么对这些值做插值。现代 CSS 提供了property可以注册一个带类型和初始值的变量property --progress { syntax: number; inherits: false; initial-value: 0; } .bar::after { content: ; display: block; width: calc(var(--progress) * 100%); height: 4px; background: var(--brand-color, #2563eb); transition: --progress 0.4s ease; } .bar:hover::after { --progress: 1; }注册之后浏览器知道--progress是一个数字类型就会在 0 到 1 之间做平滑过渡进度条也能像普通属性一样动起来。需要说明的是property是较新的能力使用前要查一下目标浏览器的支持情况。对兼容性要求严格的场景可以退回去用 JS 配合setProperty驱动虽然不是 CSS 纯方案但同样能享受到只用改一个变量的好处。5.4 结合 JS 的进度条例子如果不想依赖property用 JS 推动进度也能写得非常干净const bar document.querySelector(.bar); let progress 0; const timer setInterval(() { progress Math.min(1, progress 0.1); bar.style.setProperty(--progress, progress); if (progress 1) clearInterval(timer); }, 200);CSS 那边只需要定义width: calc(var(--progress, 0) * 100%)就够了。JS 的中枢只维护一个数值变量渲染完全交给 CSS。这种“JS 管数值、CSS 管呈现”的分工在写交互组件时特别舒服。6. 兼容性、降级策略和工程化组织6.1 浏览器支持现状与何时需要回退CSS 变量目前在现代浏览器里已经是非常基础的能力但 IE11 以及更老的浏览器完全不支持。如果你的项目还有硬性的 IE 要求那就必须做好回退策略。我通常先问一个问题这个变量承担的是“锦上添花”的部分还是“核心布局”的部分。前者可以直接放弃变量后者必须加兜底。判断方式很简单打开 Can I Use 查一下当前目标用户群用的浏览器版本凡是支持var()的就用变量方案不支持的老老实实写具体值。6.2 双写兜底与 supports 检测最常见的降级是双写.btn { background: #2563eb; background: var(--btn-bg, #2563eb); }第一行给老浏览器用它不认var()就会忽略第二行新浏览器会使用第二行的变量。如果变量没有定义第二行里的回退值#2563eb也能兜住。想要更精细的控制可以用supportssupports (--custom: property) { .btn { background: var(--btn-bg, #2563eb); } }supports (--custom: property)这一句用来检测浏览器能否解析自定义属性。能解析才应用变量规则不能解析就完全走传统写法。6.3 变量命名分层与团队规范变量数量一多命名就会失控。我的习惯是分三层管理层级前缀示例使用位置全局令牌--color-*--color-primary:root主题令牌--bg-*/--text-*--bg-body主题覆盖区域组件局部--btn-*--btn-bg组件选择器内部不要让:root里堆几百个变量能放在组件局部就放在局部。局部变量可以带默认值让组件开箱即用.card { --card-bg: #ffffff; --card-radius: 12px; background: var(--card-bg); border-radius: var(--card-radius); }组件内部定义默认值外部想定制时再覆盖这样组件的“可配置性”是显式的使用方一看就知道这个组件支持哪些自定义项。6.4 与设计系统和原子化策略的共存如果团队走原子化 CSS 路线变量并没有失去意义。原子类负责提供“功能”变量负责提供“主题”和“设计令牌”。基础颜色、间距、字号的来源统一抽到变量层工具类里引用这些变量这样原子化页面也能实现整体换肤。我见过不少团队把变量当成“万能配置中心”什么值都往:root里塞最后变量文件比组件代码还难读。变量是为样式系统服务的不是用来制造新的概念负担。命名清晰、范围正确、按层分布才能让它在团队里持续产生价值。7. 我踩过的 CSS 变量坑和排查方法7.1 变量值“存在但非法”时不会走 fallback这个坑我印象特别深。第一次以为 fallback 是万能的结果被现实教育了。:root { --wrong: #2563eb; } .box { width: var(--wrong, 100px); }--wrong确实被定义了但它是一个颜色值放在width里是非法的。问题在于浏览器这里不会使用回退值100px而是把width当成unset处理最终结果相当于auto。原因就是 fallback 只在“变量未定义”时生效不会在“变量定义错了”时生效。类似的还有空值情况.danger { --color: ; background: var(--color, red); }--color被声明成了一个空值它不算未定义所以回退值也不会生效background最终会变成无效值。这种问题在代码里特别难发现因为看起来变量“有定义”你根本不会往空值方向想。7.2 空格、单位、注释把 calc 搞崩除了解析层的问题语法层的细节也会坑人。最典型的是calc()加号两侧必须留空格这个大家都听过但实操中还是源源不断有人踩。更隐蔽的是变量里带了额外空格或注释导致最终表达式不是你想的那样。还有单位拼接的问题前面提过这里再强调一遍:root { --size: 2; } .box { width: calc(var(--size)px); /* 错 */ width: calc(var(--size) * 1px); /* 对 */ }把数字和单位拼在一起的想法很自然但在 CSS 里这不是字符串拼接而是语法错误。想要数字变成长度就用乘法。7.3 变量不能进入选择器、属性名和媒体条件变量不是万能的。var()只能出现在属性声明的值里不能出现在选择器、属性名和媒体条件的查询值里下面这些写法全都不会生效media (min-width: var(--breakpoint)) {} /* 不生效 */ .main .var(--theme) {} /* 不生效 */ a { var(--color): red; } /* 不生效 */底层原因在于媒体查询、选择器这些位置需要在样式计算的很早阶段就确定而变量要到计算属性值的时候才会解析。这不是浏览器偷懒而是架构决定的。想在断点切换时用不同值正确做法是在媒体查询里重新给变量赋值。7.4 DevTools 排查三板斧如果变量没按预期生效我一般按这三步来查在 Elements 面板选中目标元素看 Styles 区里有没有对应的--*变量有没有被删除线划掉。被划掉说明有更高优先级的规则覆盖了它。切到 Computed 面板找到最终计算出的属性值确认var()到底被解析成了什么。在 Sources 里全局搜索--变量名把定义、覆盖、引用的位置全部列出来顺着链路排查。特别注意如果变量定义写在media (prefers-color-scheme: dark)内部而当前系统正好是浅色模式DevTools 里这个变量会显示为未定义。这不是 bug只是条件没命中。7.5 什么场景不该硬用变量讲了这么多变量的好处最后想泼一点冷水。变量不是越多越好。如果一个值只用一次以后基本不会变那就没必要变量化。如果团队对变量完全不熟满屏--xxx反而会让新成员看不懂。如果目标浏览器有硬性兼容要求又不打算做回退那就更不要硬用。我个人现在判断的标准很简单如果这个值在未来会随着主题或状态变化或者被两个以上地方引用就值得变量化如果它只是某个页面的一次性位移那就老老实实写死。CSS 变量是给样式系统减负的工具不是用来增加仪式感的。