CSS变量无法穿透Shadow DOM，必须声明在宿主元素上才能被内部继承；document.body或:root设置无效，因查找链止于宿主，且所有var()必须带fallback值。
不能“穿透修改”，只能在宿主元素上声明变量，让Shadow DOM内部通过继承读取——这是机制决定的，不是技巧问题。
为什么document.body.style.setProperty('--x', 'red')没用
Shadow DOM 内部的 var(--x) 查找链只向上走到宿主元素（如 <my-button>）就终止，document.body 或 :root 根本不在该链上。即使你成功设置了，getComputedStyle(host).getPropertyValue('--x') 仍返回空字符串，说明变量根本没挂到宿主上。
- 浏览器不报错，DevTools 的 computed 面板里也看不到
--x出现在 “inherited CSS properties” 列表中 - 常见误操作：把变量写在父容器上，比如
<div class="theme-dark"><my-card></my-card></div>+.theme-dark { --bg: #1e1e1e; }—— 变量没落在<my-card>自身，继承链直接中断 - iOS Safari 16.4 之前存在 WebKit 级 bug：即使变量已正确挂载，
var(--x)仍可能返回undefined
三种真正有效的挂载方式
所有方式本质都是让变量落在宿主元素自身节点上：
-
行内 style：
<my-card style="--card-bg: #f8f9fa; --text-color: #212529;"></my-card> -
CSS 规则直击宿主：必须写在 light DOM 或全局 CSS 中，且选择器精确命中宿主标签，例如
my-card[theme="dark"] { --card-bg: #1e1e1e; }或.theme-dark my-card { --card-bg: #1e1e1e; }（注意不是.theme-dark { --card-bg: ... }） -
JS 动态设置：
el.style.setProperty('--card-bg', '#f0f0f0')，不是document.body.style.setProperty，也不是shadowRoot.host.style.setProperty（后者等价但冗余）
:host 里转发变量时最常踩的坑
:host 是唯一合法的变量“落地点”，但它本身不自动继承外部变量，必须显式用 var(--x) 接住——但这里极易出错：
立即学习“前端免费学习笔记（深入）”；
-
禁止在
:host中加 fallback：:host { --bg: var(--bg, #fff); }会触发无限递归，Chrome/Firefox 可能卡死 -
绝对不要用
all: initial或all: unset在:host或shadowRoot.documentElement上，它会清空所有 CSS 变量继承，var()直接回退 fallback 且无提示 -
:host规则必须写在 shadow 内部的<style>中；外部 CSS 文件里写my-button:host完全无效
所有 var() 必须带 fallback，否则静默失效
漏掉 fallback 是主题失效最隐蔽的原因：未定义的 var(--color) 不会报错，而是让整个声明回退到 CSS 初始值（background-color: initial 是 transparent，不是白色；color: initial 是黑色，但 <a> 仍显示 UA 蓝色）。
- 正确写法：
color: var(--text-color, #333);、background-color: var(--card-bg, #ffffff); - 拼错变量名（
--btn-bk-colorvs--btn-bg-color）或大小写不一致（--Color≠--color）也会导致 fallback 生效，但 DevTools 显示为invalid而非错误 - 调试时别只看 computed，右键 Shadow 内节点 → “Show inherited CSS properties”，能直接看到变量是否被继承进来、来源是哪里、是否用了 fallback
真正容易被忽略的只有三点：变量名没统一约定、var() 漏 fallback、变量没声明在宿主元素上——任一出问题，样式就静默崩坏，控制台不报错，DevTools 里也看不出异常。
