如何在Vite驱动的Nuxt 3项目中使用Stencil实现SSR？

不需要等useHydration()的官方文档，Stencil本身自带完整的SSR水合能力，对接Nuxt 3的钩子就能实现，核心逻辑和你在Nuxt 2里的写法一致，只是钩子和配置位置有变化。

1. 前置准备 #

确保你构建的Stencil组件库已经输出了hydrate脚本（就是你在Nuxt 2中使用的dist-hydrate目录产物），同时构建时开启客户端水合注解配置，方便客户端精准匹配服务端渲染的DOM，避免水合 mismatch。

2. 配置服务端渲染逻辑 #

在nuxt.config.ts中注册渲染钩子，在HTML返回给客户端/写入静态文件前，调用Stencil的renderToString处理页面中的自定义组件标记，和Nuxt 2的generate:page逻辑完全对应，同时配置Vue编译器跳过Stencil自定义元素的编译，避免报错：

import { renderToString } from '你的Stencil组件包名/dist-hydrate'

export default defineNuxtConfig({
  // 其余Nuxt配置省略
  hooks: {
    // 服务端渲染、静态生成、本地开发场景都会触发该钩子
    'render:html': async (htmlContext) => {
      const renderResult = await renderToString(htmlContext.body, {
        prettyHtml: false,
        // 可按需添加Stencil hydrate配置，比如静态资源路径、移除水合注释等
      })
      htmlContext.body = renderResult.html
    }
  },
  vue: {
    compilerOptions: {
      // 标记Stencil组件为自定义元素，跳过Vue编译
      isCustomElement: (tagName) => tagName.startsWith('你的Stencil组件统一前缀-')
    }
  }
})

3. 配置客户端水合逻辑 #

Stencil的客户端loader会自动识别服务端渲染好的DOM结构完成水合，不需要手动对接Nuxt的水合API，只需要新建客户端插件，在浏览器环境加载Stencil的自定义元素定义即可：

// plugins/stencil.client.ts
import { defineNuxtPlugin } from '#app'
import { defineCustomElements } from '你的Stencil组件包名/loader'

export default defineNuxtPlugin(() => {
  defineCustomElements(window, {
    // 可按需配置Stencil客户端资源加载路径，和组件库构建时的publicPath对齐即可
  })
})

注意事项 #

• 上述配置同时兼容nuxt dev开发环境、nuxt build服务端部署、nuxt generate静态生成三种场景，不需要额外写分支逻辑
• Stencil组件的属性传递、事件监听按原生Web Components规范书写即可，Vue 3已经原生支持自定义元素的属性和事件绑定，不需要额外做适配
• 如果出现水合不匹配报错，优先检查Stencil构建配置中是否开启了clientHydrateAnnotations选项，开启后Stencil会在服务端渲染的DOM上添加水合标记，大幅降低mismatch概率

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