Angular 17升级后SSR不生效：页面app-root标签内容为空

核心配置检查 #

1. angular.json 配置 #

• 确认项目已启用SSR架构，检查 architect 节点下是否包含 server 和 prerender，且 build 与 server 的输出路径关联正确：

  "architect": {
    "build": {
      "outputPath": "dist/your-project/browser"
    },
    "server": {
      "builder": "@angular-devkit/build-angular:server",
      "outputPath": "dist/your-project/server",
      "options": {
        "main": "src/main.server.ts",
        "tsConfig": "tsconfig.server.json"
      }
    }
  }
  

• 验证 dev:ssr 命令配置，确保指向正确的SSR启动任务：

  "scripts": {
    "dev:ssr": "ng run your-project:serve-ssr"
  }
  

2. 入口文件配置 #

• 确认 main.server.ts 正确导出服务端启动逻辑：

  import { bootstrapApplication } from '@angular/platform-browser';
  import { AppComponent } from './app/app.component';
  import { config } from './app/app.config.server';
  
  const bootstrap = () => bootstrapApplication(AppComponent, config);
  
  export default bootstrap;
  

• 检查 app.config.server.ts 是否包含服务端渲染必备配置：

  import { mergeApplicationConfig, ApplicationConfig } from '@angular/core';
  import { provideServerRendering } from '@angular/platform-server';
  import { appConfig } from './app.config';
  
  const serverConfig: ApplicationConfig = {
    providers: [provideServerRendering()]
  };
  
  export const config = mergeApplicationConfig(appConfig, serverConfig);
  

3. 代码兼容性检查 #

• 排查根组件及路由中是否存在服务端无法执行的代码（如直接调用 window、document 等浏览器API），需用 isPlatformBrowser 包裹浏览器专属逻辑：

  import { isPlatformBrowser } from '@angular/common';
  import { Inject, PLATFORM_ID } from '@angular/core';
  
  constructor(@Inject(PLATFORM_ID) private platformId: Object) {}
  
  ngOnInit() {
    if (isPlatformBrowser(this.platformId)) {
      // 仅在浏览器端执行的代码
    }
  }
  

• 检查是否有服务端渲染阶段抛出的错误，这类错误会直接中断HTML生成，导致 app-root 为空。

4. 依赖版本一致性 #

• 确保所有Angular核心依赖版本统一为17.x，避免版本不兼容导致的SSR失效：

  "dependencies": {
    "@angular/core": "^17.0.0",
    "@angular/platform-browser": "^17.0.0",
    "@angular/platform-server": "^17.0.0"
  },
  "devDependencies": {
    "@angular-devkit/build-angular": "^17.0.0"
  }
  

调试验证步骤 #

1. 执行 ng build && ng run your-project:server，确认 dist/server 目录生成完整的服务端bundle。
2. 启动SSR服务后，查看终端日志，重点关注服务端渲染阶段的报错信息。
3. 使用 curl http://localhost:4200 直接请求页面，查看返回的HTML源码是否包含渲染后的内容。
4. 替换根组件为极简测试组件，排除业务代码导致的渲染失败。

内容的提问来源于stack exchange，提问作者Прохор ДжаваСкриптонит