升级Angular 17 SSR项目到Vite/esbuild后出现NG0908错误求助

问题核心 #

使用ng update @angular/cli --name use-application-builder升级带SSR的Angular项目到Vite构建器后，启用prerender时触发NG0908: In this configuration Angular requires Zone.js错误，关闭prerender则构建正常。这是因为预渲染流程依赖Zone.js，但当前配置中server端polyfill或Zone设置不符合要求。

解决方案 #

1. 确保server端polyfill引入Zone.js #

检查src/polyfills.server.ts文件，确认已添加Zone.js的Node环境引入：

// src/polyfills.server.ts
import 'zone.js/node'; // 必须存在，预渲染依赖Node环境下的Zone.js

2. 验证angular.json中server和prerender配置 #

打开angular.json，确认server构建目标的polyfills路径正确，且prerender目标关联正确的server配置：

{
  "projects": {
    "your-project-name": {
      "architect": {
        "server": {
          "builder": "@angular-devkit/build-angular:server",
          "options": {
            "outputPath": "dist/server",
            "main": "server.ts",
            "polyfills": "src/polyfills.server.ts", // 确保指向正确的server polyfill文件
            "tsConfig": "tsconfig.server.json"
          }
        },
        "prerender": {
          "builder": "@angular-devkit/build-angular:prerender",
          "options": {
            "routes": ["/"],
            "serverTarget": "your-project-name:server" // 确保关联正确的server构建目标
          },
          "configurations": {
            "production": {
              "browserTarget": "your-project-name:build:production"
            }
          }
        }
      }
    }
  }
}

3. 调整Zone.js的环境配置 #

如果在app.config.ts中使用了ngZone: 'noop'禁用Zone.js，需要针对预渲染的Node环境恢复默认Zone：

// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideZoneChangeDetection } from '@angular/core';

export const appConfig: ApplicationConfig = {
  providers: [
    provideZoneChangeDetection({
      eventCoalescing: true,
      runCoalescing: true,
      // 预渲染在Node环境执行，此时必须使用默认Zone；客户端可按需配置noop
      ngZone: typeof window === 'undefined' ? undefined : 'noop'
    }),
    // 其他providers...
  ]
};

注意：预渲染流程依赖Zone.js处理异步操作和变更检测，不能在Node环境下禁用Zone。

4. 清理缓存并重新构建 #

执行以下命令清理构建缓存，确保新配置生效：

ng clean && ng build

原因说明 #

关闭prerender时，SSR仅作为运行时服务端渲染，可能客户端禁用Zone的配置不会影响server端运行；但预渲染是静态页面生成流程，Angular需要Zone.js来协调Node环境中的异步任务和组件渲染，因此必须确保server端正确引入并启用Zone.js。

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