Angular 18 SSR Hydration延迟致@if/@else双渲染问题求助

问题原因 #

NG0506错误本质是服务端渲染的DOM与客户端Hydration阶段的预期DOM不匹配：

• 服务端渲染时，isPlatformBrowser返回false，模板渲染@else分支内容，生成的HTML逻辑正确。
• 客户端启动Hydration时，isPlatformBrowser在浏览器环境返回true，模板尝试渲染@if分支，导致DOM结构与服务端输出不一致，触发NG0506错误。
• 浏览器先显示服务端输出的HTML，随后Hydration过程中因客户端判断逻辑生效，短暂同时渲染两个分支，直到defer占位符执行完毕、DOM完成修正后恢复正常。

修复方案 #

方案1：使用TransferState同步环境判断状态（推荐） #

通过TransferState将服务端的环境判断结果传递到客户端，确保Hydration阶段客户端的判断逻辑与服务端完全一致，避免DOM不匹配：

import { Component, Inject, PLATFORM_ID } from '@angular/core';
import { isPlatformBrowser, TransferState, makeStateKey } from '@angular/common';

// 定义状态键
const IS_BROWSER_STATE_KEY = makeStateKey<boolean>('is-browser');

@Component({
  selector: 'app-your-component',
  template: `
    @if (isBrowser) {
      <div>客户端专属内容</div>
    } @else {
      <div>服务端/预渲染内容</div>
    }
  `,
  standalone: true
})
export class YourComponent {
  isBrowser: boolean;

  constructor(
    @Inject(PLATFORM_ID) private platformId: object,
    private transferState: TransferState
  ) {
    // 优先从TransferState读取状态，无则判断当前环境
    this.isBrowser = this.transferState.get(IS_BROWSER_STATE_KEY, isPlatformBrowser(this.platformId));
    
    // 服务端环境下，将判断结果存入TransferState
    if (!isPlatformBrowser(this.platformId)) {
      this.transferState.set(IS_BROWSER_STATE_KEY, false);
    }
  }
}

方案2：用@defer延迟客户端分支渲染 #

利用Angular的@defer语法，让客户端专属内容在Hydration完成后再渲染，避免Hydration阶段的DOM冲突：

<!-- 模板代码 -->
@defer(on hydration) {
  <div>客户端专属内容</div>
} @else {
  <div>服务端/预渲染内容</div>
}

• on hydration触发条件确保Hydration完成后才加载客户端分支，与服务端输出的DOM完全匹配，不会触发NG0506。
• 如果需要占位内容，可以自定义@placeholder块，保持与服务端输出一致。

方案3：禁用组件Hydration（不推荐） #

若上述方案无法快速落地，可临时禁用目标组件的Hydration，但会失去SSR Hydration的性能优化优势：

@Component({
  selector: 'app-your-component',
  template: `...`,
  standalone: true,
  hydration: false // 禁用该组件的Hydration
})
export class YourComponent {
  // ... 原有逻辑
}

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