StencilJS组件在SvelteKit SSR中渲染后消失问题排查

问题背景 #

• 开发了一个简单的StencilJS模板组件，已发布为npm包
• 基于SvelteKit创建模板应用，通过npm install引入该组件
• 组件在CSR（客户端渲染）模式下运行正常，但开启SSR（服务端渲染）并添加hooks.server.ts后，出现页面闪烁：组件渲染后1秒内消失
• 排查发现组件的hydrated类被自动移除，手动在开发者工具中添加该类后，组件可正常显示

解决方案尝试 #

1. 确认Stencil组件的SSR配置

检查Stencil组件库的stencil.config.ts，确保开启SSR支持及正确的输出目标：

export const config: Config = {
  enableServerSideRendering: true,
  outputTargets: [
    // 保留其他必要输出目标
    {
      type: 'dist-server',
      copy: [{ src: '**/*.css' }],
    },
  ],
};

2. 手动维护hydrated类

在SvelteKit页面或布局组件中，监听Stencil组件的hydrated事件，确保类名不丢失：

<script>
  import { onMount } from 'svelte';

  onMount(() => {
    const targetComponent = document.querySelector('your-stencil-component-tag');
    if (!targetComponent) return;

    // 初始检查补全类名
    if (!targetComponent.classList.contains('hydrated')) {
      targetComponent.classList.add('hydrated');
    }

    // 监听hydrated事件，防止类名被移除
    targetComponent.addEventListener('hydrated', () => {
      if (!targetComponent.classList.contains('hydrated')) {
        targetComponent.classList.add('hydrated');
      }
    });
  });
</script>

<your-stencil-component-tag />

3. 排查hooks.server.ts的干扰逻辑

检查hooks.server.ts中的代码，确认没有全局DOM操作、样式重置或类名清理逻辑——这些操作可能误移除Stencil组件的hydrated类。如果存在相关逻辑，调整或移除对目标组件的影响。

4. 遵循Stencil官方SSR集成规范

确保按照Stencil官方文档指引，在SvelteKit中正确集成SSR：

• 确保组件库的dist-server产物被正确引入到SvelteKit的服务端渲染流程中
• 避免在服务端渲染阶段修改客户端DOM的类名状态

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