NextJS中使用StencilJS Web组件触发Hydration水合报错问题

API 探路者

2026-8-27

NextJS 适配 Stencil 自定义表单组件 Hydration 异常解决方案

问题背景

在NextJS项目中引入Stencil构建的非Shadow DOM模式Web组件时，会触发水合失败报错：

Hydration failed because the initial UI does not match what was rendered on the server.
将组件切换为shadow: true模式后水合报错消失，但原生FormData无法采集Shadow DOM内部的表单字段值。

方案一：快速屏蔽报错（功能无异常仅需消除提示场景）

该水合报错仅在next dev开发环境下作为阻断提示抛出，生产环境构建后不会触发，所有功能可正常运行，无强制修复要求。
开发环境如果需要消除该提示，最稳妥的方式是让Stencil组件跳过服务端渲染，从根源避免SSR输出与客户端初始渲染结构不一致。封装一个客户端专属渲染包裹组件即可：

// components/ClientOnly.jsx
'use client'
import { useEffect, useState } from 'react'

export default function ClientOnly({ children, fallback = null }) {
  const [mounted, setMounted] = useState(false)
  useEffect(() => setMounted(true), [])
  return mounted ? children : fallback
}

使用时直接包裹Stencil生成的React组件：

<form ref={formRef} onSubmit={handleSubmit}>
  <ClientOnly>
    <TestInput name='damn' label='labeltest' onInput={handleInput} />
  </ClientOnly>
  <button type='submit'>submit</button>
</form>

不想包裹组件的话，也可以直接给Stencil组件添加React原生支持的suppressHydrationWarning属性，仅关闭当前元素的水合差异校验，不会影响其他组件的水合逻辑：

<TestInput 
  name='damn' 
  label='labeltest' 
  onInput={handleInput}
  suppressHydrationWarning
/>

方案二：彻底修复水合问题，同时解决Shadow DOM表单值采集问题

修复水合不匹配问题

水合报错的核心原因是服务端渲染时Stencil自定义元素还未完成注册，被浏览器当作普通未知标签渲染，客户端加载完Stencil脚本后才替换为真实组件结构，导致前后输出不一致。

提前加载Stencil组件脚本，保证页面水合执行前所有自定义元素已经完成注册。如果用App Router，在根布局app/layout.js中使用NextJS的Script组件，设置脚本加载策略为beforeInteractive，同步加载组件定义：

import Script from 'next/script'

export default function RootLayout({ children }) {
  return (
    <html lang="zh-CN">
      <body>
        {/* 替换为你自己项目中Stencil构建产物的路径 */}
        <Script 
          src="/build/your-stencil-components.esm.js" 
          type="module" 
          strategy="beforeInteractive" 
        />
        {children}
      </body>
    </html>
  )
}

Pages Router项目可以在_document.js中同步引入该脚本即可。

修复Shadow DOM模式下FormData采集失效问题

保留Shadow DOM的样式隔离能力的前提下，不需要把组件改回light DOM，用原生表单特性即可解决采集问题：

给外层表单设置唯一ID，将ID传入Stencil组件，给Shadow DOM内部的input元素添加原生form属性，关联到外层表单，浏览器会自动把该input识别为对应表单的字段，FormData可以正常采集值。
修改Stencil组件代码：

@Component({
  tag: 'test-checkbox',
  shadow: true, // 保留Shadow DOM样式隔离
})
export class TestCheckbox {
  @Prop() name: string;
  @Prop() value: boolean;
  @Prop() label: string;
  @Prop() innerValue: string;
  @Prop() formId: string; // 接收外层表单ID

  render() {
    const { value, name, formId, label } = this;
    return (
      <div>
        <label htmlFor={name}>{label}</label>
        <input 
          type="checkbox" 
          name={name} 
          id={name} 
          checked={!!value}
          form={formId} // 绑定外层表单
        />
      </div>
    );
  }
}

页面中使用方式：

import { useRef, useId } from 'react'

const Form = () => {
  const formRef = useRef();
  const formId = useId(); // 生成唯一ID避免多表单冲突
  
  const handleInput = (e) => {
    // 原有逻辑
  };

  const handleSubmit = (e) => {
    e.preventDefault();
    const formData = new FormData(e.target);
    // 可正常获取到Shadow DOM内的字段值
    console.log(formData.get('damn'));
  };

  return (
      <form ref={formRef} id={formId} onSubmit={handleSubmit}>
        <TestInput 
          name='damn' 
          label='labeltest' 
          formId={formId}
          onInput={handleInput} 
        />
        <button type='submit'>submit</button>
      </form>
  );
};

export default Form

如果不方便修改Stencil组件源码，可以在表单提交回调中，手动遍历所有嵌套Shadow DOM内的表单元素，将值追加到FormData中即可。

内容的提问来源于stack exchange，提问作者PixelRepublik

NextJS中使用StencilJS Web组件触发Hydration水合报错问题

问题背景 #

方案一：快速屏蔽报错（功能无异常仅需消除提示场景） #

方案二：彻底修复水合问题，同时解决Shadow DOM表单值采集问题 #

修复水合不匹配问题 #

修复Shadow DOM模式下FormData采集失效问题 #

问题背景

方案一：快速屏蔽报错（功能无异常仅需消除提示场景）

方案二：彻底修复水合问题，同时解决Shadow DOM表单值采集问题

修复水合不匹配问题

修复Shadow DOM模式下FormData采集失效问题