Angular 17升级后'window is not defined'错误的排查方案

问题详情 #

升级到Angular 17并使用新的Vite构建器后，执行ng build时出现如下错误：

An unhandled exception occurred: window is not defined
详细信息请查看"/private/var/folders/gv/n0kqs93x29v30b0cfl5tzr140000gn/T/ng-6nQUx1/angular-errors.log"

日志文件未提供有效信息，且已将所有涉及window的代码放入afterNextRender()逻辑中，需要获取更多错误排查信息。

项目依赖配置如下：

{
  "name": "frontend",
  "version": "0.0.0",
  "scripts": {
    "ng": "ng",
    "start": "ng serve", 
    "build": "ng build",
    "test": "ng test",
    "lint": "ng lint",
    "e2e": "ng e2e"

  },
  "private": true,
  "dependencies": {
    "@angular/animations": "^17.3.12",
    "@angular/cdk": "^16.2.12",
    "@angular/common": "^17.3.12",
    "@angular/compiler": "^17.3.12",
    "@angular/core": "^17.3.12",
    "@angular/forms": "^17.3.12",
    "@angular/localize": "^17.3.12",
    "@angular/platform-browser": "^17.3.12",
    "@angular/platform-browser-dynamic": "^17.3.12",
    "@angular/platform-server": "^17.3.12",
    "@angular/router": "^17.3.12",
    "@angular/service-worker": "^17.3.12",
    "@angular/ssr": "^17.3.11",
    "@ckeditor/ckeditor5-angular": "^9.0.0",
    "@ckeditor/ckeditor5-build-classic": "^42.0.0",
    "@ckeditor/ckeditor5-core": "^42.0.0",
    "@ckeditor/ckeditor5-engine": "^42.0.0",
    "@ckeditor/ckeditor5-utils": "^42.0.0",
    "@ckeditor/ckeditor5-watchdog": "^42.0.0",
    "@fullcalendar/angular": "^6.1.5",
    "@fullcalendar/core": "^6.1.5",
    "@fullcalendar/daygrid": "^6.1.5",
    "@fullcalendar/interaction": "^6.1.5",
    "@ng-bootstrap/ng-bootstrap": "^16.0.0",
    "@ng-select/ng-select": "~12.0.7",
    "@popperjs/core": "^2.11.7",
    "@sentry/angular": "^8.38.0",
    "@sentry/tracing": "^7.114.0",
    "@stripe/stripe-js": "^3.0.0",
    "@types/topojson": "^3.2.3",
    "bootstrap": "5.2.3",
    "canvas": "^2.11.2",
    "chart.js": "^4.2.1",
    "chartjs-adapter-date-fns": "^3.0.0",
    "chartjs-chart-geo": "4.1.2",
    "date-fns": "^2.29.3",
    "express": "^4.18.2",
    "localstorage-polyfill": "^1.0.1",
    "ng2-charts": "^5.0.0",
    "ng2-pdf-viewer": "10.3.4",
    "ngx-colors": "3.5.3",
    "ngx-infinite-scroll": "^17.0.0",
    "ngx-stripe": "^17.0.0",
    "rxjs": "^6.6.7",
    "tslib": "^2.5.0"
  },
  "dependenciesMeta": {
    "@fullcalendar/angular": {
      "injected": true
    }},
  "devDependencies": {
    "@angular-devkit/build-angular": "^17.3.11",
    "@angular-eslint/builder": "~17.3.0",
    "@angular-eslint/eslint-plugin": "~17.3.0",
    "@angular-eslint/eslint-plugin-template": "~17.3.0",
    "@angular-eslint/schematics": "~17.3.0",
    "@angular-eslint/template-parser": "~17.3.0",
    "@angular/cli": "~17.3.11",
    "@angular/compiler-cli": "~17.3.12",
    "@types/express": "^4.17.17",
    "@types/jasmine": "^3.6.11",
    "@typescript-eslint/eslint-plugin": "^7.2.0",
    "@typescript-eslint/parser": "^7.2.0",
    "browser-sync": "^3.0.0",
    "ckeditor5": "^42.0.0",
    "eslint": "^8.56.0",
    "eslint-config-prettier": "^8.8.0",
    "eslint-plugin-prettier": "^4.2.1",
    "jasmine-core": "3.8",
    "jasmine-spec-reporter": "~5.0.0",
    "karma": "~6.3.4",
    "karma-chrome-launcher": "^3.1.1",
    "karma-coverage": "~2.0.3",
    "karma-jasmine": "^4.0.2",
    "karma-jasmine-html-reporter": "^1.7.0",
    "prettier": "^2.8.7",
    "sass": "^1.61.0",
    "sass-loader": "^13.2.2",
    "ts-node": "^10.9.1",
    "typescript": "~5.4.5",
    "webpack": "^5.78.0"
  }
}

排查方法 #

• 启用详细构建日志：执行ng build --verbose，输出完整构建流程，定位错误发生的具体模块或阶段。
• 排查第三方依赖：从依赖列表看，CKEditor、FullCalendar、ng2-pdf-viewer等可能在初始化时直接访问window。可临时移除这些依赖，逐步验证哪个包触发了错误。
• 配置Vite SSR外部化：在angular.json的build配置中，将浏览器专属依赖标记为外部化，避免服务器端构建时处理：

  "architect": {
    "build": {
      "builder": "@angular-devkit/build-angular:application",
      "options": {
        "ssr": {
          "external": ["@ckeditor/ckeditor5-build-classic", "@fullcalendar/angular"]
        }
      }
    }
  }
  

• 条件导入浏览器依赖：结合isPlatformBrowser判断环境，动态导入浏览器专属模块：

  import { isPlatformBrowser } from '@angular/common';
  import { Inject, PLATFORM_ID } from '@angular/core';
  
  constructor(@Inject(PLATFORM_ID) private platformId: Object) {}
  
  ngOnInit() {
    if (isPlatformBrowser(this.platformId)) {
      import('@ckeditor/ckeditor5-build-classic').then(module => {
        // 初始化CKEditor逻辑
      });
    }
  }
  

• 检查Polyfill加载时机：确保localstorage-polyfill等浏览器相关Polyfill在应用启动前加载，避免服务器端执行时缺失环境变量。
• 验证SSR代码逻辑：所有组件/服务中，除afterNextRender()或isPlatformBrowser()包裹的代码外，其他逻辑需避免直接访问window等浏览器API。

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