CSS变量无法穿透到Shadow DOM内部，除非明确挂载在宿主元素上；浏览器查找时只沿DOM树向上、不跨Shadow Boundary，:root或body声明无效，必须用行内style或直接命中宿主的CSS规则声明，并始终带fallback值。
CSS变量无法穿透到Shadow DOM内部，除非明确挂载在宿主元素上——这不是限制，而是Shadow DOM继承机制的必然结果。
变量必须声明在宿主元素上，否则var(--x)始终fallback
浏览器查找CSS变量时只沿DOM树向上，不跨Shadow Boundary。写:root { --color: red; }或body { --color: red; }对Shadow内节点完全无效。
- 正确方式只有两种：
<my-button style="--color: #28a745;">（行内），或my-button { --color: #28a745; }（该CSS规则必须直接命中宿主标签） - 小程序中更严格：需用
<van-button class="theme-dark">+.theme-dark { --btn-bg: #333; }，写在父<view>上无效 - Vue/React等框架中，父组件加
class或style传入变量，子Web Component才能读到
所有var()必须带fallback，否则样式静默失效
var(--bg-color)未定义时，整个CSS声明会被丢弃（如background变成transparent），没有任何警告。
- 必须写成
background: var(--bg-color, #007bff);，哪怕只是临时占位 - 常见可定制项建议全覆盖：
color: var(--text-color, #333);、border-radius: var(--radius, 4px);、box-shadow: var(--shadow, 0 1px 3px rgba(0,0,0,0.1)); - 拼错变量名（如
--btn-bk-colorvs--btn-bg-color）是主题失效最隐蔽的原因
调试时别只看computed，要查“inherited CSS properties”
Elements面板中右键Shadow内节点 → “Show inherited CSS properties”，能直接看到该节点实际继承到哪些变量值。
立即学习“前端免费学习笔记（深入）”；
- 比手动调
getComputedStyle(el).getPropertyValue('--color')更直观、更可靠 - 这个面板会清晰显示变量来源（来自宿主style属性？来自宿主CSS规则？还是fallback？）
- 若列表里没出现你的变量，说明挂载位置错误，不是变量没生效，而是根本没被继承进来
真正容易被忽略的点就三个：变量名没统一约定、var()漏掉fallback、变量没声明在宿主元素上——任一出问题，主题就会在某个组件里静默失效，控制台不会报错，DevTools里也看不出异常。
