Angular Universal构建及服务端渲染时document未定义错误求助

我之前帮不少开发者踩过Angular Universal的这个坑，其实核心原因特别明确：服务端渲染是在Node.js环境跑的，这里没有浏览器专属的document、window这类DOM API，而你用到的jQuery初始化代码直接把document当参数传入，自然会触发ReferenceError。

给你几个递进的解决方案，从最彻底到应急兜底的都有：

1. 优先移除jQuery依赖（最推荐） #

Angular本身提供了一套完整的DOM操作API，完全可以替代jQuery的大部分场景——比如元素选择、样式修改、事件绑定这些。直接移除jQuery是从根源解决问题的办法，还能减少项目体积，避免前后端环境差异带来的各种兼容性问题。

2. 动态加载jQuery，仅在浏览器环境执行 #

如果项目确实离不开jQuery，那就把它的加载和调用逻辑限制在浏览器环境里：

• 利用Angular的isPlatformBrowser工具判断当前环境，再动态引入jQuery：

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

@Component({
  selector: 'app-your-component',
  templateUrl: './your-component.component.html'
})
export class YourComponentComponent {

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

  ngAfterViewInit(): void {
    // 只在浏览器端加载并执行jQuery代码
    if (isPlatformBrowser(this.platformId)) {
      // 方式1：动态创建script标签加载CDN的jQuery
      const script = document.createElement('script');
      script.src = 'https://code.jquery.com/jquery-3.7.1.min.js';
      script.onload = () => {
        $(document).ready(() => {
          // 这里写你的jQuery业务逻辑
          $('.target-element').hide();
        });
      };
      document.body.appendChild(script);

      // 方式2：用动态import加载本地安装的jQuery
      // import('jquery').then($ => {
      //   $(document).ready(() => {
      //     // 你的jQuery操作
      //   });
      // });
    }
  }
}

3. 服务端模拟DOM环境（应急兜底方案） #

如果是第三方依赖硬啃document没法修改，可以用domino库在Node环境模拟一套浏览器DOM：

• 先安装依赖：npm install domino --save-dev
• 在服务器入口文件（通常是server.ts）顶部添加模拟代码：

import * as domino from 'domino';
const fs = require('fs');
const path = require('path');

// 读取项目的index.html作为模拟DOM的模板
const template = fs.readFileSync(path.join(__dirname, './dist/你的项目名/browser/index.html')).toString();
// 创建模拟的window和document对象
const win = domino.createWindow(template);
global['window'] = win;
global['document'] = win.document;
global['navigator'] = win.navigator;

⚠️ 注意：这种模拟只是“看起来像”浏览器环境，部分复杂的DOM API可能无法完美适配，尽量只作为临时应急方案。

4. 用Angular原生API替代jQuery操作 #

Angular推荐用Renderer2来操作DOM，它会自动适配服务端渲染环境，不会出现未定义错误：

import { Component, Renderer2, ElementRef } from '@angular/core';

@Component({
  selector: 'app-your-component',
  templateUrl: './your-component.component.html'
})
export class YourComponentComponent {

  constructor(private renderer: Renderer2, private el: ElementRef) { }

  ngOnInit(): void {
    // 比如给元素添加类名（替代jQuery的$('.target').addClass('active')）
    const targetElement = this.el.nativeElement.querySelector('.target');
    this.renderer.addClass(targetElement, 'active');
  }
}

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