CSS变量失效最隐蔽高频的原因是变量名拼写不一致：定义为--primary-color，引用时写成--primay-color或--primaryColor，浏览器静默失败；须确保大小写、连字符、字母数完全一致，并在DevTools的Styles面板中核对变量是否被正确定义和继承。
变量名拼写不一致直接导致失效
这是最隐蔽也最高频的问题：定义时是 --primary-color，引用时写成 --primay-color 或 --primaryColor，浏览器不会报错，但 var(--primay-color) 会安静地 fallback（如果提供了回退值）或完全无效（没提供则该属性被丢弃）。
常见陷阱包括多一个字母（--alllports vs --allports）、大小写混用（--BgColor 和 --bgcolor 是两个变量）、中划线位置错误（--text-color 正确，--text_color 无效）。
- 打开开发者工具 → Elements 面板 → 选中目标元素 → 在 Styles 面板里搜索你的变量名，确认它是否出现在“Computed”或“Styles”中
- 复制定义处的变量名（含所有连字符和大小写），粘贴到引用处，避免手敲出错
- 不要依赖 IDE 自动补全——CSS 变量补全支持差，且补全项可能来自旧缓存
:root 未声明或声明位置错误
--primary-color 写在 .card { --primary-color: red; } 里，却在 body 上用 var(--primary-color)，那它根本不可见。自定义属性必须在作用域内声明才能被读取，而 :root 是最常用、最安全的全局声明位置。
- 确保变量定义包裹在合法选择器内：
:root { --color: #007bff; }✅；--color: #007bff;（无选择器）❌，浏览器直接忽略整行 - 媒体查询内部可以声明变量，但不能把
:root放在媒体查询外层再套一层——@media (min-width: 768px) { :root { --size: 24px; } }是合法的；但:root { @media (...) { --size: 24px; } }❌，语法非法 - 如果用 JS 动态设置，
document.documentElement.style.setProperty('--color', 'red')等价于在:root声明，优先级高于 CSS 文件中的同名变量
var() 回退值不生效的典型误判
var(--color, #ccc) 的回退值只在变量**完全未定义**或**值本身非法**时触发。如果 --color 被定义为 transparent、inherit、空字符串或 0（缺单位），它依然算“有效”，回退值永远不会启用。
PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。
- 检查变量是否真的未定义：在 Elements → Styles 面板里搜索
--color，看它是否出现在“Custom Properties”区域；若没出现，说明声明失败或被覆盖 - 避免用语义上“无效”的值充当代替方案，比如
--bg: none;——none是合法值，var(--bg, white)不会 fallback - 调试时可临时加一句
content: var(--missing-var, 'MISSING');到伪元素上，直接在页面看到 fallback 是否触发
动画中使用自定义属性时的重绘缺失
用 --progress 控制 @keyframes 中的 transform: scaleX(var(--progress))，但动画只跳变、不过渡——问题不在变量本身，而在浏览器没触发重绘或初始值为 0 导致 from→to 无变化。
立即学习“前端免费学习笔记（深入）”；
- 确保动画触发前，变量已有非零、非初始默认值（如
--progress: 0.01;而非0） - 强制重绘：修改变量后，加一行
el.offsetHeight;（读取布局）或el.style.transform = 'scaleX(1)';触发重排 - 不要在
@keyframes内直接赋值自定义属性（from { --progress: 0; }❌），只能用它驱动其他属性；动画逻辑应由 JS 控制变量，CSS 负责响应
