CSS变量未生效主因是引用链断裂，90%未进入渲染阶段：拼写错误、作用域错位（非:root定义）、Shadow DOM未继承、组件库未启用CSS变量支持、JS动态设置漏--前缀或改错对象。
改了 :root 里的 CSS 变量，但组件颜色没变——不是变量没更新，是引用链断了。90% 的情况根本没走到渲染阶段，变量压根没被读取。
为什么 var(--color-primary) 显示为 “invalid” 或没反应
开发者工具里鼠标悬停在 var(--color-primary) 上显示 unresolved，说明浏览器连变量名都没找到。常见原因：
-
--color-primary拼写错误（比如--color-pirmary），浏览器静默 fallback 到初始值，不报错 - 变量定义在某个 class 内部（如
.theme-dark { --color-primary: #1e40af; }），但目标元素不在该作用域下，读不到 - 定义位置错误：写在
body或组件 scoped style 里，而不是:root；:root是唯一能保证全局可读的位置 - Shadow DOM 中未显式传入变量，父级定义的
--color-primary不会自动穿透
第三方组件（Ant Design / Bootstrap / Element Plus）不响应变量
这些库默认硬编码颜色，不读你的 --primary-color。必须确认是否启用 CSS 变量支持：
- Ant Design 5+：需在
ConfigProvider加theme={{ cssVar: true }}，否则所有变量都是摆设 - Bootstrap 5.2+：只改
--bs-primary不够，必须同步设置--bs-primary-rgb（格式必须是74, 111, 165，不能带括号或单位），否则rgba(var(--bs-primary-rgb), .1)解析失败 - Element Plus：需用
el-config-provider开启css-var，并指定namespace（如ep），变量名变成--ep-primary-color - Vue/React 组件内部若渲染到
body底部（如 Modal、Tooltip），仍读:root，失效一定是变量漏设，不是 DOM 位置问题
改了 document.documentElement.style.setProperty() 却没生效
JS 修改后 computed styles 里还是旧值，大概率卡在语法或作用域上：
立即学习“前端免费学习笔记（深入）”；
- 漏掉双短横线前缀：
setProperty('primary-color', '#3b82f6')❌，必须是setProperty('--primary-color', '#3b82f6')✅ - 传数字不加引号：
setProperty('--alpha', 0.3)在部分 Safari 上异常，写成'0.3'更稳 - 改的是
document.body.style而非document.documentElement.style—— body ≠ :root，伪类和根级样式可能根本没继承到 - 变量虽已修改，但目标元素有内联
style="color: red"，直接覆盖var()级联结果
深色模式或构建流程导致变量“被覆盖”
页面加载后颜色又回退，不是 JS 没执行，而是后续样式重写了变量或作用域冲突：
- 构建工具（如 Vite/Webpack）把第三方 UI 库的 CSS 插入到了你的主题文件之前，导致
:root声明被后加载的样式覆盖 - 组件内部自己定义了同名变量（如
.card { --text-color: #1f2937; }），就近原则优先，屏蔽了:root的值 - 深色模式媒体查询里只写了
color: var(--text-color);，没提供 fallback（如color: #333; color: var(--text-color, #333);），JS 未加载或变量未定义时就失效 - Tailwind 等框架若用
@layer base插入默认样式，它默认在最前，可能压掉你手动写的:root—— 得确保主题 CSS 在@layer base之后注入
最容易被忽略的是：变量名大小写、连字符、-- 前缀、RGB 格式、作用域嵌套层级，四者只要一处错，整条链路就静默中断，且浏览器不报任何错误。
