Angular Universal SSR在服务器端未返回HTML内容问题排查

1. 对齐服务器与本地的Node.js版本 #

• 确保服务器上的Node.js版本和本地完全一致（包括主、次版本），Angular Universal对Node版本兼容性要求严格，版本不匹配会导致渲染逻辑静默失败。
• 执行node -v对比本地和服务器版本，若不一致，升级或降级服务器Node版本。

2. 验证构建产物完整性 #

• 本地执行yarn build:ssr后，将dist目录完整复制到服务器，不要拆分复制文件。
• 服务器构建前，先删除node_modules和yarn.lock，重新执行yarn install --production，避免依赖缓存引发异常。

3. 检查domino全局对象模拟是否完整 #

确保server.ts中domino覆盖了所有SSR需要的浏览器API，示例正确配置：

import * as domino from 'domino';
const win = domino.createWindow('');
global['window'] = win;
global['document'] = win.document;
global['navigator'] = win.navigator;
// 按需添加其他需要模拟的API，比如localStorage
global['localStorage'] = {
  getItem: () => '',
  setItem: () => {},
  removeItem: () => {}
};

• 遗漏浏览器API模拟会导致渲染中途失败，最终<app-root>无内容。

4. 修正Nginx反向代理配置 #

确保Nginx将请求转发给SSR服务，而非直接返回静态文件：

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:4000; # 对应SSR服务启动端口
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # 静态资源直接从dist/browser读取
    location /assets {
        alias /path/to/your/dist/browser/assets;
        expires 1y;
    }

    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        root /path/to/your/dist/browser;
        expires 1y;
    }
}

• 查看Nginx错误日志（/var/log/nginx/error.log），排查反向代理或静态资源路径错误。
• 禁止Nginx直接返回index.html，必须让请求先经过SSR服务处理。

5. 查看SSR服务运行日志 #

• 先在前台启动SSR服务（yarn dev:ssr或node dist/server/main.js），观察控制台是否有渲染报错（部分错误不会终止服务，仅静默跳过渲染）。
• 若用PM2管理进程，执行pm2 logs查看详细日志，定位具体失败点。

6. 检查组件的SSR兼容性 #

• 排查所有组件，避免在ngOnInit或构造函数中直接调用未模拟的浏览器API。
• 使用isPlatformServer区分环境，跳过SSR时的浏览器专属逻辑：

import { isPlatformServer } from '@angular/common';
import { Inject, PLATFORM_ID } from '@angular/core';

constructor(@Inject(PLATFORM_ID) private platformId: Object) {}

ngOnInit() {
  if (!isPlatformServer(this.platformId)) {
    // 仅在浏览器端执行的代码，比如初始化第三方JS库
  }
}

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