Next.js引入Stencil Web Components出现服务端额外属性警告如何解决

• Next.js默认开启服务端渲染（SSR/SSG），服务端返回HTML时，Stencil构建的Web Components还未初始化执行，不会生成shadow DOM内部的class属性
• 客户端hydration阶段，Stencil组件完成初始化，自动在shadow DOM中附加了class属性，React会比对服务端与客户端的DOM结构差异，识别到额外的class属性后触发该警告，属于React对自定义元素的校验误报。

提供3种适配方案，可根据项目场景选择：

方案1：单组件禁用hydration警告（最轻量化） #

直接在出现警告的自定义元素标签上添加suppressHydrationWarning属性，告诉React跳过该元素的hydration属性校验：

<my-ui-icon suppressHydrationWarning />

该方案只会屏蔽单个元素的警告，不会影响其他组件的正常校验逻辑，适合只有少量自定义元素出现警告的场景。

方案2：全局配置自定义元素白名单 #

如果项目中用到大量Stencil自定义元素，可在next.config.js中全局配置React自定义元素识别规则，告诉React这些标签属于自定义元素，无需做严格的hydration属性校验：

// next.config.js
module.exports = {
  compiler: {
    react: {
      // 填入你所有Stencil组件库输出的自定义元素标签名
      customElements: ['my-ui-icon', 'my-ui-button', 'my-ui-card']
    }
  }
}

配置完成后重启项目即可生效。

方案3：关闭自定义元素所在模块的SSR #

如果Web Components本身强依赖客户端API运行，可使用next/dynamic将用到自定义元素的模块设置为仅客户端渲染，服务端不会输出对应DOM结构，从根源避免hydration不匹配问题：

// 引入组件时关闭SSR
import dynamic from 'next/dynamic'
const Navbar = dynamic(() => import('./components/navbar'), {
  ssr: false
})

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