:host-context(.dark) 不生效的根本原因是它只能匹配直接祖先的精确类名，不跨 Shadow DOM 边界，且不响应动态添加的类；需确保 .dark 在组件挂载前已存在于其父级元素上。
:host-context(.dark) 为什么经常不生效
根本原因在于 :host-context() 只能向上匹配**直接祖先元素**的类名，且该祖先必须是 Web Component 的**父级或更上层容器**（不能跨 Shadow DOM 边界反向查找），同时它**不支持动态类名变更后的重计算**——类名在组件挂载后才加上的，:host-context() 不会响应。
常见错误现象：.dark 已加在 或 上，但组件内样式没变；或者祖先用了 class="theme-dark" 却写成 :host-context(.dark) —— 类名必须完全一致。
-
:host-context()的选择器必须精确匹配祖先元素的 class 列表中的某个 token，不支持部分匹配或正则 - 如果祖先元素是
<div class="container dark-mode">，就得写 <code>:host-context(.dark-mode)，而不是.dark - Shadow DOM 内部无法通过
:host-context()感知到或的类——因为它们不是该组件的“上下文祖先”（context ancestor），中间隔着 document 根节点
正确使用 :host-context(.dark) 的前提条件
必须确保目标祖先元素既是 DOM 父级（或祖父级等），又明确携带对应类名，并位于同一文档流中。典型可行结构：
<div class="dark"> <my-button></my-button> </div>
此时 <my-button></my-button> 的 shadow root 中可安全使用：
立即学习“前端免费学习笔记（深入）”；
:host-context(.dark) {
--bg-color: #1e1e1e;
background: var(--bg-color);
}
- 祖先元素必须是
<my-button></my-button>的**直系或间接父元素**（不能是兄弟、不能是 body 的子元素而 button 是 body 的孙子） - 类名必须在组件
connectedCallback执行前就已存在；若用 JS 动态添加，需手动触发样式更新（例如this.shadowRoot.adoptedStyleSheets = [...]或强制重 render） - 不支持嵌套上下文，如
:host-context(.dark):host-context(.compact)是无效语法；多个条件要用空格连接：:host-context(.dark .compact)表示祖先需同时含两个类（且 .compact 是 .dark 的后代）
替代方案：当 :host-context() 失效时该用什么
绝大多数实际项目中，:host-context() 因结构限制不可靠，更健壮的做法是监听祖先类变化或主动注入主题状态。
- 用
MutationObserver监听document.body的class属性变更，然后调用组件内部方法切换 CSS 变量：this.style.setProperty('--bg-color', '#1e1e1e') - 在 custom element 构造函数中读取
document.documentElement.classList.contains('dark')，初始化时设置data-theme="dark"属性，再用:host([data-theme="dark"])控制样式 - 配合 CSS 自定义属性 +
:root声明，让所有组件继承：:root.dark { --bg-color: #1e1e1e; } my-button { background: var(--bg-color); }（注意：这要求组件未禁用继承，且未在 shadow root 中覆盖:root）
兼容性与性能注意事项
:host-context() 在 Chromium 63+、Firefox 94+ 支持，但 Safari 16.4+ 才开始支持（iOS Safari 16.5+），旧版 Safari 完全忽略该伪类，不会报错也不会回退——样式静默失效。
- 不要依赖它做关键视觉降级；务必提供默认浅色样式作为 fallback
- 每个
:host-context()规则都会触发浏览器向上遍历 DOM 树，大量组件高频使用可能影响渲染性能（尤其深层嵌套时） - 与
:host()组合使用时注意优先级：:host(.active):host-context(.dark)是合法的，但:host-context(.dark) .inner中的.inner仍受 shadow scope 限制，无法穿透到 light DOM
真正难的不是写对那行 CSS，而是确认祖先类名是否在正确的层级、是否及时存在、以及 Safari 用户看到的到底是什么——这些细节一旦漏掉，暗色模式就只在你本地 Chrome 里生效。
