Angular 19中@defer(hydrate never)导致元素为空的问题排查

场景与期望 #

在Angular 19中尝试使用新增的增量水合（Incremental Hydration）特性，目标是通过@defer (hydrate never)让服务器返回已渲染为静态内容的组件HTML，同时不加载该组件的JavaScript，以此提升初始页面性能。

代码实现 #

延迟加载组件配置 #

@defer (hydrate never) {
  <app-block-hero [content]="block" />
}

组件类（基于Signals API） #

@Component({
  selector: 'app-block-hero',
  ...
})
export class AppBlockHeroComponent {
  readonly content = input.required<CMSBlockHero>();
}

组件模板 #

<h1>{{ content().title }}</h1>
... 其他内容 ...

增量水合全局配置 #

provideClientHydration(
  ...
  withIncrementalHydration()
),

问题现象 #

实际运行后，<h1>标签内无任何内容，完全为空。

原因分析 #

使用@defer (hydrate never)时，服务器端会完成组件的静态渲染，但客户端不会对该组件执行水合操作——这意味着组件类的逻辑完全不会被执行，Signals输入也不会被初始化绑定。

你的模板中{{ content().title }}依赖于Signals的响应式求值，但在hydrate never模式下，客户端不会初始化content输入信号，自然无法解析出title值。

更关键的是，Angular客户端会将服务器渲染的静态DOM替换为客户端生成的空模板（因为组件未水合，没有数据绑定逻辑支撑），最终导致原本服务器渲染好的内容被清空。

解决方案 #

要实现“服务器渲染静态内容+不加载组件JS”的需求，可按以下方式调整：

• 避免在组件模板中使用依赖组件类的语法（如Signals输入、组件方法调用等）
• 改用纯静态模板，或者直接在服务器端将数据注入为模板的静态内容，而非通过组件输入传递

如果必须保留组件的动态逻辑，则不能使用hydrate never，可选择其他延迟水合策略（比如@defer (on idle)），让客户端在空闲时完成水合，确保Signals能正常工作。

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