根本原因是变量未定义在当前继承链上：css变量仅在声明选择器及其后代中可见，var(--x)向上查找时若父容器未匹配或未声明该变量，就会返回空或fallback值。
CSS自定义属性在组件作用域里读取不到，根本不是“没生效”，而是变量压根没被定义在当前继承链上——var(--x)向上查找时，跳过了你预期的父容器。
为什么var(--text-color)在子组件里返回空或fallback值
因为变量只在声明它的选择器及其后代中“可见”。你在:root里定义了--text-color: #333，但子组件根节点没匹配到:root（它不是:root的后代，而是独立挂载的DOM片段），或者你把变量写在某个局部.card里，却指望兄弟组件也能读到。
常见错误包括：
- 在 Vue 的
<style scoped></style>里写.card { --color: red; }，但子组件没加class="card"，导致变量无处落脚 - React 中用
styled-components包裹子组件，父组件设的style={{ '--color': 'red' }}没透传到该 DOM 节点上 - 小程序中只在
app.wxss定义--space-md，但页面index.wxss没@import，变量根本没加载
:root定义的变量为何在 Shadow DOM 或第三方组件里失效
Shadow DOM 有自己独立的样式作用域，:root 不穿透；第三方组件（如 Element Plus）若未启用 css-var 模式，其内部样式压根不引用 var(--primary-color)，你改了全局变量也没用。
解决方案要分场景：
- Vue 组件内：显式给根元素加 class，比如
<div class="theme-light">...</div>，再在<style scoped></style>里写.theme-light { --text-color: #1a1a1a; } - React + styled-components：别依赖 JS theme 对象传颜色，直接在 wrapper 元素上设
style={{ '--primary-color': theme.primary }} - Element Plus：必须启用
<el-config-provider :css-var="true"></el-config-provider>，否则所有--el-color-primary都是摆设
JavaScript 动态设置变量却没反应，可能漏了节点参数
document.documentElement.style.setProperty('--x', 'red') 是写到 :root，但如果你操作的是局部组件容器，比如一个 <div id="user-card">，就得明确指定节点：<code>userCardEl.style.setProperty('--x', 'red')。否则变量写到了全局，而子元素只认离它最近的那个有效定义 —— 如果中间某层没设，就会一路查到 :root，但你又没在那里设，结果 fallback 就生效了。
另外注意：
- Vue 的
<style scoped></style>不影响变量查找逻辑，但如果你的组件根元素没 class、也没显式绑定主题类，var(--x)就只能 fallback 到:root定义的默认值 - 小程序没有
document.documentElement，JS 设置无效；得靠setData触发 class 切换，再在 WXSS 里用.dark-mode { --text-color: #fff; }这种方式
最容易被忽略的一点：CSS 变量不是“值传递”，而是“定义位置绑定”。你以为设了一次就能到处用，其实每个组件都得有自己的变量快照，否则继承链一断，var() 就只能干瞪眼。
