CSS变量失效主因是拼写错误、作用域越界或语法不规范：变量名严格区分大小写且须双短横开头，定义必须在:root或有效作用域内，引用需用var()并配合法单位与原子属性。
检查 CSS 变量是否被识别为无效值
浏览器对 --my-var 这类自定义属性名完全大小写敏感且严格匹配，拼错一个字母（比如 --priamry-color）或少一个连字符（--bgcolor），就会静默回退到初始值或继承值——控制台不报错，Computed 面板里对应属性直接消失或显示为 invalid。
在开发者工具的 Elements 面板选中目标元素，切换到 Computed 标签页，搜索你期望生效的属性（如 background-color 或 color）。如果该属性压根没出现，或出现了但值是 initial/inherit，而你确定写了 var(--xxx)，那大概率是变量名拼错了。
- 用
getComputedStyle($0).getPropertyValue('--xxx')在控制台手动查，返回空字符串就说明变量未定义 - 注意：即使
:root里定义了--alllports（三个 l），但引用时写成var(--allports)（两个 l），浏览器不会提示，只当没这变量 - 变量名中多一个空格、下划线或中文字符（如
--bg color）也属于非法命名，会被忽略
确认变量定义与引用位置是否在作用域内
CSS 变量遵循级联和作用域规则：:root 定义的变量全局可用，但若在某个选择器内部（如 .card { --primary: red; }）定义，就只对该选择器及其后代生效。引用时超出这个范围，变量就不可见。
常见错误是把变量定义在局部作用域，却在外部样式中引用；或者变量定义在媒体查询内部，但引用发生在常规样式块里，导致非响应条件下变量根本不存在。
立即学习“前端免费学习笔记（深入）”；
- 打开 Elements 面板，右键目标元素 → “Reveal in Elements panel”，再点右侧 Styles 面板顶部的“filter”图标，输入变量名，看是否有定义来源
- 检查变量是否被包裹在
@media或@supports中，而当前视口/环境不满足条件 - 避免在伪元素（如
::before）里定义变量后，试图在父元素上引用它——作用域不向上穿透
验证 var() 函数调用语法是否完整
var() 不是万能兜底：它必须搭配合法的 CSS 属性使用，且 fallback 值不能缺失单位或格式不当。例如 background: var(--bg); 可能失效，因为 background 是复合属性，而 --bg 若只存颜色值（如 #fff），浏览器无法确定该填到哪个子属性上。
更稳妥的做法是指定具体属性，比如用 background-color: var(--bg); 或 color: var(--text-primary, #333);，并确保 fallback 有合理默认值。
-
var(--size)用于font-size时，--size必须带单位（如16px），否则计算失败 - 多个
var()连用（如calc(var(--a) + var(--b))）时，任一变量未定义，整个表达式失效 - 不要在
@keyframes内部直接引用未在 :root 或动画作用域中定义的变量
用 DevTools 快速比对定义与引用的拼写
最高效的排查方式不是肉眼扫代码，而是利用浏览器自带的跳转能力。在 Styles 面板中，鼠标悬停在 var(--xxx) 上，Chrome / Edge 会显示一个小箭头，点击即可跳转到该变量定义处；Firefox 则支持 Ctrl+Click 跳转。
如果点击后跳转失败，或跳转到一个空行/注释行，说明这个变量名在当前样式表中根本没定义过——这时候立刻回头检查拼写，比逐行 grep 更快。
- VS Code 用户可安装“CSS Peek”插件，同样支持 Ctrl+Click 跳转定义
- 别依赖编辑器高亮：有些拼写错误（如
--color-primaryvs--colour-primary）编辑器不会标红，但浏览器不认 - 变量名含数字时特别容易错，比如
--border-2和--border-2x看似接近，实则完全不同
变量拼写问题最难缠的地方在于它不抛错、不报警、不打断流程，只悄悄让样式“蒸发”。最可靠的判断依据永远是 Computed 面板里那个本该出现却不见踪影的属性值，而不是代码看起来“差不多”。
