使用11ty构建Stencil组件库文档时通过prerender搭配hydration解决路由切换闪烁问题

核心实现逻辑与需求对齐：在11ty完成静态页面预渲染的基础上，接入Stencil的水合能力完成最终交互绑定，从根源上消除Stencil客户端启动等待期的内容闪烁。

构建阶段链路打通 #

• 在11ty构建流程中接入Stencil的服务端渲染能力，不要等待纯静态HTML输出到磁盘后，再交由客户端运行Stencil脚本。具体通过11ty的addTransform钩子，调用Stencil导出的renderToString方法，将11ty生成的整页HTML字符串传入，由Stencil将所有自定义组件直接渲染为携带完整属性、序列化Shadow DOM内容的静态HTML，再写入站点产物目录。
• 调整Stencil水合脚本的注入位置，将水合所需的核心启动脚本内联到页面<head>的最前部，避免外引脚本的网络加载延迟，保证脚本尽可能早执行。

路由切换体验优化 #

• 依托11ty的静态路由特性，每个独立路由页面本身已经携带了完整的预渲染Stencil组件HTML结构。切换路由时仅替换页面内容区域的HTML片段即可，不要提前清空内容容器等待组件挂载；Stencil的水合逻辑会自动识别已存在的组件节点，完成事件绑定与状态关联，不会出现内容空白期。
• 为所有Stencil自定义标签配置预渲染态的基础样式兜底，在11ty的全局CSS中提前声明组件宿主元素的尺寸、颜色、排版规则，哪怕水合脚本尚未执行，页面布局也和最终渲染态保持一致，不会出现布局跳变。

水合流程性能调优 #

• 开启Stencil hydrate配置中的serializeShadowRoot选项，将每个组件的Shadow DOM内容直接序列化为静态HTML节点，不需要客户端在水合阶段从零创建Shadow DOM结构。
• 对非首屏可见的组件，保留静态渲染的HTML内容，仅在组件进入视口时再执行对应的水合绑定流程，大幅缩短首次水合的脚本执行时长。

常见避坑点 #

• 不要在Stencil组件的componentWillLoad生命周期中直接修改DOM内容覆盖预渲染的静态结果，否则水合阶段会因内容不匹配触发节点重建，重新引入闪烁问题。
• 构建阶段要校验11ty模板输出的组件属性、类名和Stencil组件内部渲染逻辑的一致性，避免水合匹配失败导致的节点重绘。

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