Web Components 声明式 Shadow DOM 如何用于服务端渲染

Web Components 要用于服务端渲染，关键不是让服务端执行 attachShadow()，而是直接在返回的 HTML 中把组件内部结构写成 。支持该能力的浏览器在解析文档时，会把这个模板转换成宿主元素的 Shadow Root；样式、插槽和服务端内容因此可以在组件 JavaScript 下载之前就进入正确的 DOM 边界。

客户端代码随后只负责“激活”：复用已经存在的 shadowRoot，绑定事件、状态和数据更新，不要再次重建服务端已经输出的结构。这正是声明式 Shadow DOM（Declarative Shadow DOM，DSD）连接 SSR 与 Custom Elements 的核心用法。

MDN 官方文档：https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM

故障现场：HTML 有内容，首屏仍然先出现空壳

传统客户端组件通常先输出一个空宿主，等 JavaScript 执行后再调用 attachShadow()、写入样式和内部节点。网络慢或主线程繁忙时，用户会先看到空白、自定义元素的 Light DOM 裸内容，或者一瞬间的无样式内容；等 Shadow Root 建好后，布局又发生变化。

轻量键盘

class ProductCard extends HTMLElement {
  connectedCallback() {
    // 客户端较晚创建 Shadow Root，首屏结构和样式都会后到
    const root = this.attachShadow({ mode: "open" });
    root.innerHTML = `
`;
  }
}

customElements.define("product-card", ProductCard);

根因不是服务端没有输出文本，而是 Shadow Root 只能由客户端脚本晚一步创建。服务端给出的 Light DOM 与客户端后来构造的 Shadow Tree 属于两个阶段，浏览器无法在初始解析时就得到完整组件边界。

修复动作：服务端直接输出声明式 Shadow Root

最小可用写法是在自定义元素宿主内部放置一个带 shadowrootmode 的 template。值可以是 open 或 closed，与 attachShadow({ mode }) 的模式一致。SSR 场景通常先用 open，这样升级后的组件可以通过 this.shadowRoot 复用服务端结构。

轻量键盘
  面向移动办公的紧凑配列

浏览器解析这段文档时，会把 template 内容附着到父元素 product-card 的 Shadow Root。支持 DSD 的 DOM 中不会留下这个模板元素，而会得到“宿主 + Shadow Root + slot 投影”的结构。即使 Custom Element 还没有注册，服务端渲染的主体和封装样式也已经存在。

服务端模板应该承担哪些内容

服务端应输出用户第一眼需要的稳定内容：组件结构、首屏文本、可序列化属性、Shadow Tree 内部样式以及 slot 的 Light DOM 数据。事件监听器、临时状态、网络重试和浏览器对象不属于 HTML 序列化内容，应留给客户端激活。

多个实例可以重复输出相同的内部样式。浏览器能够复用相同外部样式表的底层资源；若把简短关键样式直接内联，组件又能在流式 HTML 到达时尽快获得正确外观。实际选择取决于缓存策略、CSP 和首屏要求。

客户端激活：复用已有 Shadow Root

组件升级后不要无条件调用 attachShadow()。对于 open 模式，先检查 this.shadowRoot；存在就直接查询服务端节点并绑定事件，不存在才建立客户端回退结构。这样“结构由服务端给，行为由客户端接管”，不会清空已经渲染的内容。

class ProductCard extends HTMLElement {
  connectedCallback() {
    // 防止元素重复连接时重复绑定事件
    if (this.dataset.hydrated === "true") return;

    let root = this.shadowRoot;

    if (!root) {
      // 仅用于没有服务端 DSD 或回退脚本未运行的环境
      root = this.attachShadow({ mode: "open" });
      root.innerHTML = `
        

          

          收藏
        
`;
    }

    const button = root.querySelector('[data-action="favorite"]');
    button?.addEventListener("click", () => {
      // 激活阶段只更新交互状态，不重建服务端 DOM
      button.setAttribute("aria-pressed", "true");
      button.textContent = "已收藏";
    });

    this.dataset.hydrated = "true";
  }
}

customElements.define("product-card", ProductCard);

这里的“激活”比完整框架 hydration 更轻：没有对整棵树做虚拟 DOM 对账，只是把行为附着到服务端已经生成的节点。如果组件状态复杂，也可以在服务端把可序列化初值放到属性或 Light DOM 中，再由客户端读取。

兼容回退：先检测，再转换模板

不要把固定浏览器版本写死在业务逻辑里。可以检测 HTMLTemplateElement.prototype 是否具有 shadowRootMode 属性。不支持时，浏览器会保留普通 template[shadowrootmode]；回退脚本可以扫描模板，把其内容移动到父元素新建的 Shadow Root，再注册 Custom Elements。

function supportsDeclarativeShadowDOM() {
  // 标准属性存在时，由浏览器解析器负责创建 Shadow Root
  return Object.prototype.hasOwnProperty.call(
    HTMLTemplateElement.prototype,
    "shadowRootMode",
  );
}

function attachFallbackRoots(root = document) {
  if (supportsDeclarativeShadowDOM()) return;

  root.querySelectorAll("template[shadowrootmode]").forEach((template) => {
    const host = template.parentElement;
    const mode = template.getAttribute("shadowrootmode");

    // 只接受标准模式，避免把未知值传给 attachShadow
    if (!host || (mode !== "open" && mode !== "closed")) return;

    const shadow = host.attachShadow({ mode });
    shadow.append(template.content);
    template.remove();

    // 处理 Shadow Tree 内部可能嵌套的声明式模板
    attachFallbackRoots(shadow);
  });
}

attachFallbackRoots();

回退脚本应尽量早于组件注册执行，否则组件构造函数可能先看到没有 Shadow Root 的宿主并创建另一套结构。closed 模式下页面代码不能通过 element.shadowRoot 读取根节点，组件若需要在升级时访问声明式 closed root，应使用与组件设计匹配的内部访问方案；普通 SSR 组件优先采用 open 模式更容易维护。

最容易踩的 parser-only 陷阱

声明式 Shadow DOM 是 HTML 解析器能力，不是给任意 template 后补一个属性就能生效。下面的动态创建只会得到普通模板，父元素不会自动出现 Shadow Root：

const host = document.createElement("div");
const template = document.createElement("template");

// 动态设置属性不会触发声明式 Shadow Root 解析
template.setAttribute("shadowrootmode", "open");
host.append(template);

console.log(host.shadowRoot); // null

同样，普通 innerHTML 和 insertAdjacentHTML() 的片段解析不会应用声明式 Shadow Root。初始 SSR 响应由文档解析器处理，不受这个问题影响；如果确实需要在运行时解析可信 HTML 并包含 DSD，应使用平台提供的专用解析 API，例如 setHTMLUnsafe() 或 Document.parseHTMLUnsafe()，同时把来源校验和注入风险作为独立安全边界处理，不能把不可信字符串直接交给这些 API。

const trustedHTML = `
  `;

const container = document.createElement("div");

// 仅对服务端已信任并完成安全处理的 HTML 使用专用解析 API
container.setHTMLUnsafe(trustedHTML);

为什么重复 attachShadow 会破坏 SSR 内容

浏览器为兼容旧组件，对已经拥有声明式 Shadow Root 的宿主调用匹配模式的 attachShadow() 时，可以返回该 root，但会清空已有内容。于是代码看起来没有抛错，服务端结构却被擦掉，再由客户端重新写入，SSR 的首屏收益也随之消失。

防复发规则很简单：升级代码先读已有 root，只有 root 不存在时才进入回退分支；事件绑定要具备幂等标记；服务端模板和客户端选择器共享稳定的 data-* 钩子，但不要让客户端复制整段服务端 HTML 作为常规路径。

上线前检查清单

• 服务端把 template[shadowrootmode] 放在 Shadow Host 内部，而不是放在无关容器。
• 首屏结构、slot、关键文本和封装样式已经包含在响应 HTML 中。
• 客户端组件先复用 this.shadowRoot，不无条件调用 attachShadow()。
• 事件绑定有幂等保护，元素断开再连接时不会重复监听。
• 兼容回退在 Custom Elements 注册前执行，并能递归处理嵌套组件。
• 动态字符串不使用普通 innerHTML 期待 DSD 生效。
• 专用动态解析 API 只接收可信、经过安全处理的 HTML。
• open 与 closed 模式从服务端到客户端保持一致。

常见问题

声明式 Shadow DOM 是否必须配合 Custom Elements？

不必须。普通元素也可以作为 Shadow Host。Custom Elements 的价值是后续自动升级和绑定行为，两者组合更适合可复用 SSR 组件。

服务端模板中的 style 会污染外部页面吗？

不会。模板被解析为 Shadow Root 后，内部样式作用于该 Shadow Tree；页面样式也不会普通地穿透边界修改内部节点。

为什么模板在 DOM 中找不到了？

支持 DSD 的浏览器在文档解析时会把模板内容变成 Shadow Root，模板本身不会作为普通子节点留下。这也可以作为兼容回退设计时的重要差异。

SSR 后还需要 JavaScript 吗？

静态展示、封装样式和 slot 投影不一定需要 JavaScript；按钮、输入、网络请求和状态更新仍需要客户端激活。目标是把“可见结构”和“交互行为”拆开，而不是取消所有脚本。

最终的职责划分是：服务端序列化稳定结构和首屏数据，HTML 解析器创建 Shadow Root，Custom Element 升级后复用已有 DOM 并补上行为。只要避免普通片段解析、无条件 attachShadow 和重复事件绑定，声明式 Shadow DOM 就能把 Web Components 自然地接入服务端渲染。