Angular 15预渲染引入Bootstrap 5报document未定义问题排查

为什么Bootstrap 5会在导入阶段访问document？ #

Bootstrap 5的JS核心库和typed.js这类工具库的设计逻辑存在本质差异：

• typed.js属于调用式工具，只有当你主动实例化类、调用方法时才会访问DOM对象；
• 而Bootstrap 5的部分组件（比如模态框、下拉菜单）在模块被导入解析时就会执行初始化逻辑——比如检测document是否存在、绑定全局DOM事件、初始化基础交互逻辑，哪怕你只是写了import { Modal } from 'bootstrap'，整个Bootstrap包的代码在加载时就已经触发了document的访问，这就导致预渲染的Node环境（无document对象）直接报错。

如何定位具体调用document的文件？ #

1. 查看错误栈的原始信息 #

执行npm run prerender时，报错信息里的**调用栈（stack trace）**会直接显示触发错误的文件路径和行号。比如：

ReferenceError: document is not defined
    at Object.<anonymous> (/path/to/project/node_modules/bootstrap/dist/js/bootstrap.js:123:45)
    ...

直接打开对应文件的对应行，就能看到是哪段代码访问了document。如果错误栈被压缩混淆，暂时换成Bootstrap的未压缩版本（比如导入bootstrap/dist/js/bootstrap.bundle.js），栈信息会更清晰。

2. 手动拦截document访问并打印调用栈 #

在预渲染的入口文件（比如main.server.ts或server.ts）中，在导入Bootstrap之前，给Node环境模拟一个带钩子的document对象，触发访问时自动打印调用栈：

// 仅在非浏览器环境执行
if (typeof document === 'undefined') {
  (global as any).document = new Proxy({}, {
    get(target, prop) {
      console.error(`触发document.${String(prop)}访问，调用栈：`);
      console.error(new Error().stack);
      return undefined;
    }
  });
}

重新执行预渲染，就能看到精准的调用链路，定位到具体代码位置。

3. 用动态导入彻底规避预渲染时的加载问题 #

既然静态导入会触发问题，就改用动态导入，配合isPlatformBrowser确保只在浏览器环境加载Bootstrap：

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

@Component({
  selector: 'app-your-component',
  templateUrl: './your-component.component.html'
})
export class YourComponent implements OnInit {
  constructor(@Inject(PLATFORM_ID) private platformId: Object) {}

  async ngOnInit() {
    if (isPlatformBrowser(this.platformId)) {
      // 仅浏览器环境动态导入Bootstrap
      const { Modal } = await import('bootstrap');
      // 此处再实例化Modal
      const modal = new Modal(document.getElementById('example-modal'));
    }
  }
}

额外的替代方案 #

如果不想手动处理环境兼容，可以直接使用ng-bootstrap——这是专门为Angular封装的Bootstrap组件库，完全适配服务器端渲染/预渲染场景，不需要手动处理document、window的环境判断，直接像普通Angular组件一样使用即可。

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