Declarative Shadow DOM 是什么，为什么服务端渲染需要它
传统 attachShadow() 只能在客户端 JS 中调用，服务端（如 Node.js、SSR 框架）无法执行 JS，因此无法生成 Shadow Root。Declarative Shadow DOM 提供了纯 HTML 方式声明 Shadow Root，让服务端能直接输出带作用域样式的结构——关键在于用 <template shadowroot="open"></template> 或 <template shadowroot="closed"></template> 元素，浏览器解析时会自动将其内容提升为 Shadow Root。
服务端如何输出合法的 Declarative Shadow DOM 标记
必须满足三个条件，缺一不可：
-
<template></template>必须是shadowroot属性的唯一载体，且该属性值只能是"open"或"closed"（大小写敏感，不能写Open或OPEN） -
<template></template>必须是其宿主元素的**直接子节点**（不能嵌套在<div> 里再塞进去） <li>宿主元素不能是自闭合标签（如 <code><img>、<input>），必须是可含子节点的元素（如<div>、<code><article></article>），且<template></template>紧跟其后正确示例（服务端可直接输出）：
<div id="my-widget"> <template shadowroot="open"><style>h1 { color: blue; }</style> <h1>Hello from Shadow</h1> </template> </div>常见错误：浏览器静默忽略或报错
以下写法服务端能输出，但浏览器不会创建 Shadow Root，且不报错（极难排查）：
- 把
<template shadowroot="open"></template>放在<div><template></template></div>内部 —— 宿主变成<div> 的父元素，而它没有子节点，导致失效 <li>使用 <code><template shadowrootmode="open"></template>（属性名错）或<template shadow-root="open"></template>（用了短横线） - 宿主元素是
<span></span>且后面没换行/空格就直接写<template></template>—— 某些模板引擎会吞掉空白，导致<template></template>不被识别为直接子节点 - 服务端输出了
<template shadowroot="open"></template>，但客户端 JS 又调用了el.attachShadow()—— 浏览器会拒绝重复附加，抛出Failed to execute 'attachShadow' on 'Element': Shadow root has already been initialized - 同一个宿主元素上，不能同时存在 Declarative Shadow DOM 和后续
attachShadow()调用 —— 后者会失败 - 若服务端已输出
<template shadowroot="open"></template>，客户端应跳过初始化逻辑，可通过检查el.shadowRoot !== null判断 - CSS 作用域只对 Shadow Root 内部生效；外部样式（如
body .my-widget h1）无法穿透，这是预期行为，不是 bug
与 CSR 组件共存时的关键约束
如果页面部分由客户端框架（如 Lit、Stencil）管理，它们默认仍用
attachShadow()，和 Declarative Shadow DOM 并存时需注意：Declarative Shadow DOM 的核心价值不在“炫技”，而在让 SSR 输出真正具备样式隔离能力的组件片段——但它的容错率很低，属性名、位置、宿主类型，三者错一个，Shadow Root 就不会出现，而且毫无提示。
- 把
