Angular 17升级用CommonEngine SSR报错NG0402：依赖注入缺失

错误原因 #

Angular 17重构了SSR的底层实现，CommonEngine的初始化逻辑和旧版renderModule差异明显：

1. 旧版renderModule会隐式处理浏览器环境相关依赖的注入，而CommonEngine要求显式配置服务端/客户端的环境依赖，若缺失则会触发依赖注入树找不到服务的NG0402错误——提示的BrowserModule实际是因为DomSanitizer等浏览器核心服务未被正确提供。
2. Angular 17的独立组件模式与NgModule模式的SSR配置逻辑不同，混用或配置不全时也会触发该错误。

解决办法 #

针对NgModule模式 #

• 确保根NgModule正确导入BrowserModule过渡配置：在AppModule中替换普通BrowserModule为BrowserModule.withServerTransition({ appId: 'your-unique-app-id' })，该配置用于区分服务端与客户端的渲染状态，确保依赖注入树包含浏览器环境必需服务。
• 服务端引导代码正确绑定根NgModule：在服务端入口文件（如main.server.ts）中，将CommonEngine的bootstrap参数指向根NgModule，示例代码：

import { CommonEngine } from '@angular/ssr';
import { AppModule } from './app/app.module';

const engine = new CommonEngine();

async function handleRender(req, res) {
  try {
    const html = await engine.render({
      bootstrap: AppModule,
      document: '<!doctype html><html><body><app-root></app-root></body></html>',
      url: req.url,
      publicPath: '/',
    });
    res.status(200).send(html);
  } catch (err) {
    res.status(500).send(err.toString());
  }
}

• 检查ServerModule导入：确保服务端专属NgModule（若有）正确导入ServerModule，避免重复或缺失核心模块。

针对独立组件模式 #

• 显式提供客户端Hydration依赖：在服务端引导时，通过provideClientHydration()注入浏览器环境必需的服务，示例代码：

import { CommonEngine } from '@angular/ssr';
import { AppComponent } from './app/app.component';
import { bootstrapApplication } from '@angular/platform-browser';
import { provideClientHydration } from '@angular/platform-browser';

const engine = new CommonEngine();

async function handleRender(req, res) {
  try {
    const html = await engine.render({
      bootstrap: () => bootstrapApplication(AppComponent, {
        providers: [provideClientHydration()]
      }),
      document: '<!doctype html><html><body><app-root></app-root></body></html>',
      url: req.url,
      publicPath: '/',
    });
    res.status(200).send(html);
  } catch (err) {
    res.status(500).send(err.toString());
  }
}

• 排查第三方依赖：避免在服务端代码中导入仅浏览器端可用的第三方模块，这类模块可能引入未被服务端环境支持的依赖，导致注入失败。

通用排查步骤 #

• 清理依赖并重新构建：执行rm -rf node_modules && npm install && npm run build:ssr（根据包管理器替换为yarn/pnpm命令），排除依赖版本不兼容问题。
• 核对Angular 17 SSR迁移步骤：确保已完全替换旧版renderModule调用为CommonEngine的render方法，且@angular/ssr包版本与其他Angular核心包版本一致。

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