什么是 Angular SSR 的 CommonEngineRenderOptions

CommonEngineRenderOptions 是 Angular 中用于服务器端渲染 (SSR) 的重要配置选项之一。它属于 @angular/platform-server 包的一部分，该包提供了服务端的渲染引擎，可以在服务器上进行 Angular 应用的预渲染，并将渲染好的 HTML 发送给客户端，这样就可以提高应用的初始加载速度并优化 SEO 表现。

在服务端渲染过程中，Angular 依赖的核心模块之一便是 CommonEngine，而 CommonEngineRenderOptions 是传递给 CommonEngine 的配置选项。CommonEngine 使用这些配置来决定如何渲染应用以及需要应用哪些中间逻辑。

Angular Universal 与 CommonEngine

Angular Universal 是 Angular 提供的一套工具，用于在服务端运行 Angular 应用。通常，Angular Universal 主要用于提升首屏加载性能以及改善搜索引擎优化（SEO）。Angular Universal 在服务端渲染应用时，使用 @angular/platform-server 库中的核心组件和函数。CommonEngine 就是这一库中关键的渲染引擎，而 CommonEngineRenderOptions 则是配置 CommonEngine 的关键选项。

CommonEngine 的作用是使用传递的渲染选项，将 Angular 应用的组件树渲染为 HTML 字符串。通过这种方式，用户第一次请求页面时，可以直接获得服务端渲染的静态 HTML 页面，而不需要等待 JavaScript 在客户端完全加载和编译。

CommonEngineRenderOptions 的主要作用

CommonEngineRenderOptions 作为渲染引擎的配置项，允许开发者自定义渲染过程中的行为。它的主要作用包括以下几个方面：

1. 应用的入口模块：配置渲染过程中需要使用的应用模块，通常是 Angular 的根模块，例如 AppServerModule。
2. document 文件的模板：用于 SSR 渲染的 HTML 模板，这个模板会被动态地填充并生成渲染后的 HTML。
3. 请求与响应上下文：可以提供请求和响应对象，供渲染引擎使用，帮助处理用户请求并生成相应的渲染内容。
4. url：提供渲染的 URL，用于标识需要渲染的页面路径，确保 SSR 引擎能够针对特定的 URL 渲染出正确的内容。
5. Providers：可以为渲染过程自定义依赖注入的内容，使得渲染的过程更加灵活。

这些功能确保了开发者在使用 CommonEngine 进行服务端渲染时可以有足够的自定义空间，能够控制应用在服务端的渲染行为和渲染内容。

CommonEngineRenderOptions 的具体参数详解

CommonEngineRenderOptions 具有多个可配置的参数，这些参数可以控制渲染引擎的行为，下面是对每个参数的详细解释。

• bootstrap: 这是一个用于应用引导的函数，通常用于引导 Angular 应用模块。在 SSR 中，可以传递 AppServerModule 来作为应用的入口模块。

• document: 一个 HTML 字符串，通常是一个 HTML 文件的模板，比如 index.html。这个模板包含基础的 HTML 骨架，<app-root> 标签是应用的占位符，Angular 会将渲染的应用内容插入到这个标签中。

• url: 这是当前需要渲染的页面的 URL，渲染引擎会基于这个 URL 确定要渲染的内容。这个参数对于动态路由特别有用，可以确保不同的请求路径渲染出不同的页面。

• providers: 用于注入一些特定的依赖，比如应用在渲染过程中需要的请求和响应上下文，或者一些环境特定的服务。

• publicPath: 该参数用于指定静态资源的路径，帮助服务器正确地引入应用所需的静态文件（例如，样式、图片等）。

使用 CommonEngineRenderOptions 的示例

为了更好地理解 CommonEngineRenderOptions 的作用，我们来看一个具体的例子，演示如何在一个 Angular Universal 项目中使用 CommonEngineRenderOptions 进行服务端渲染。

示例背景

假设我们有一个 Angular 项目，使用 Angular Universal 为其添加 SSR 支持。下面的代码演示了如何使用 CommonEngine 以及 CommonEngineRenderOptions 来渲染 Angular 应用。

首先，我们需要在项目中安装 Angular Universal 所需的包：

ng add @nguniversal/express-engine

这个命令会自动配置 Angular Universal 所需的代码，包括 Express 服务代码和 Angular 配置。

示例代码

在我们的 Express 服务中，通常会看到如下配置代码：

import 'zone.js/node';
import { ngExpressEngine } from '@nguniversal/express-engine';
import { AppServerModule } from './src/main.server';
import * as express from 'express';
import { join } from 'path';
import { CommonEngine, CommonEngineRenderOptions } from '@angular/platform-server';

const app = express();
const distFolder = join(process.cwd(), 'dist/your-app/browser');
const indexHtml = join(distFolder, 'index.html');

const commonEngine = new CommonEngine();

// 配置服务器端渲染的路由
app.get('*', (req, res) => {
  const options: CommonEngineRenderOptions = {
    document: indexHtml,
    url: req.url,
    bootstrap: AppServerModule,
    providers: [
      { provide: 'REQUEST', useValue: req },
      { provide: 'RESPONSE', useValue: res },
    ],
  };

  commonEngine.render(options).then(html => {
    res.status(200).send(html);
  }).catch(err => {
    res.status(500).send(`渲染出错: ${err.message}`);
  });
});

代码解析

在上面的代码中，我们通过 CommonEngine 来处理所有进入服务器的请求，并渲染 Angular 应用：

1. 引入和初始化：
   首先我们导入了 CommonEngine 和 CommonEngineRenderOptions，并创建了一个 CommonEngine 的实例 commonEngine。

2. 路由配置：
   在 Express 应用中为所有路由配置了 SSR 处理逻辑。每当有请求到达时，都会调用 commonEngine.render() 方法来进行页面渲染。

3. 配置 CommonEngineRenderOptions：
   使用 CommonEngineRenderOptions 来配置渲染的细节。选项中设置了 document 为 index.html 的路径，这个文件是我们 Angular 应用的基础模板文件。url 设置为请求的路径，bootstrap 设置为 AppServerModule，即应用的入口模块。providers 中我们为渲染过程提供了请求和响应对象。

关键参数说明

• document: 这里使用了 indexHtml 文件，表示渲染引擎将使用这个 HTML 模板文件。模板中通常包含 <app-root></app-root> 占位符，渲染后的内容会被插入到这里。

• url: 设置为请求路径 req.url，渲染引擎根据不同的 URL 渲染不同的内容，确保页面路径正确。

• bootstrap: 引导模块为 AppServerModule，它是 Angular 应用在服务端运行时的入口模块。

• providers: 注入请求和响应对象 req 和 res，这些对象在渲染过程中可能被一些服务使用，比如 HTTP 拦截器等。

CommonEngineRenderOptions 的实际应用场景

CommonEngineRenderOptions 通常应用于以下场景：

SEO 优化

对大多数网站来说，SEO 是关键目标之一。通常 Angular 应用在客户端进行渲染，这意味着搜索引擎抓取工具可能无法获取到完整的页面内容。而通过 SSR，我们可以在服务端将页面内容渲染成静态 HTML，再返回给客户端，从而极大地改善 SEO 性能。通过 CommonEngineRenderOptions 的 url 选项，可以让服务器针对不同路径渲染不同的页面，确保搜索引擎可以获取到完整且准确的内容。

提升用户体验

对于某些网络环境较差的用户，客户端渲染（CSR）可能会导致较长的首屏白屏时间。通过使用 SSR 并使用 CommonEngineRenderOptions 配置，我们可以在服务器端将页面渲染为 HTML，用户在初次加载时可以直接看到完整的页面内容，从而提升用户体验。

自定义渲染逻辑

通过 providers，CommonEngineRenderOptions 允许开发者在渲染过程中自定义依赖注入的逻辑。例如，可以根据请求的 headers 注入一些特定的配置，或者根据用户的地理位置定制渲染内容。这些配置使得 SSR 过程更加灵活多变，适应不同的应用场景。

代码示例：动态数据注入

CommonEngineRenderOptions 的 providers 功能非常强大，它允许我们在服务端渲染过程中注入特定的数据。比如我们可以在服务端判断用户的设备类型，然后为移动端用户注入特定的数据，从而渲染出针对移动端优化的页面。

代码示例

import { REQUEST, RESPONSE } from '@nguniversal/express-engine/tokens';

app.get('*', (req, res) => {
  const isMobile = req.headers['user-agent'].includes('Mobile');

  const options: CommonEngineRenderOptions = {
    document: indexHtml,
    url: req.url,
    bootstrap: AppServerModule,
    providers: [
      { provide: REQUEST, useValue: req },
      { provide: RESPONSE, useValue: res },
      { provide: 'IS_MOBILE', useValue: isMobile }
    ],
  };

  commonEngine.render(options).then(html => {
    res.status(200).send(html);
  }).catch(err => {
    res.status(500).send(`渲染出错: ${err.message}`);
  });
});

解析

• 注入设备类型信息：
  在渲染的 providers 中注入了 IS_MOBILE，用于标识当前请求是否来自移动设备。这样我们可以在 Angular 组件中根据 IS_MOBILE 值来决定渲染移动端特定的样式或内容。

• 组件中的应用：
  在 Angular 应用的某个服务中，可以通过依赖注入来使用 IS_MOBILE 值，从而决定如何渲染页面的内容。

import { Inject, Injectable } from '@angular/core';

@Injectable({
  providedIn: 'root'
})
export class DeviceService {
  constructor(@Inject('IS_MOBILE') private isMobile: boolean) {}

  public getDeviceType(): string {
    return this.isMobile ? 'mobile' : 'desktop';
  }
}

通过这种方式，开发者可以在服务器端渲染时为不同的设备提供不同的渲染策略，增强应用的灵活性。

主要特性总结

• document: 用于指定 HTML 模板文件，渲染内容会插入其中。
• url: 标识需要渲染的页面路径，确保不同 URL 渲染不同内容。
• bootstrap: 指定引导模块，用于初始化应用的入口。
• providers: 用于注入请求和响应上下文等其他动态数据，定制渲染逻辑。

通过这些配置，我们可以实现复杂且灵活的服务器端渲染，为用户提供更好的体验和优化的页面内容。