Angular 12项目npm start启动正常但浏览器空白报错问题排查

安装阶段出现的废弃依赖警告、Windows平台fsevents可选依赖跳过提示、普通依赖漏洞告警均不会触发运行时阻断问题，不需要在这类提示上耗费排查时间，peer依赖缺失、环境版本不匹配、本地配置缺失是这类问题的核心诱因，按以下顺序排查即可：

1. 先解决依赖版本一致性问题 #

• Angular 12对依赖版本敏感度极高，直接执行npm install会按照semver规则拉取符合版本范围的最新子包，很容易出现兼容问题。先删除本地node_modules目录和package-lock.json文件，如果仓库中已提交锁文件，拉取仓库内的原始锁文件后执行npm ci做干净安装，不要手动更新任何依赖版本。
• 执行node -v校验本地Node.js版本，Angular 12仅兼容Node.js 12.14.x、14.15.x、16.x三个大版本，本地如果是17及以上版本，会出现ES语法兼容报错直接导致页面空白，切换到16.x LTS版本后重新安装依赖即可。

2. 结合浏览器控制台报错定向处理 #

打开浏览器开发者工具切到Console面板，根据报错类型对应处理：

• 如果出现zone.js相关、polyfill相关、ES语法不识别报错：检查tsconfig.json中target字段配置，Angular12默认适配es2017，如果配置成更高版本会在低版本浏览器或者高版本Node环境下触发语法错；同时检查angular.json中build配置的polyfills数组，必须引入zone.js。
• 如果出现第三方组件undefined is not a function、构造函数不存在的报错：就是安装阶段的peer依赖缺失导致，顺着报错栈找到对应的第三方包，手动安装兼容Angular12的对应版本即可，比如ngx-bootstrap适配Angular12的版本为8.x，不要安装9.x及以上版本。
• 如果出现environment变量未定义报错：检查src/environments目录下是否存在environment.ts文件，这类本地环境配置文件通常会被加入.gitignore，新拉代码时容易缺失，直接复制同目录下的environment.prod.ts改名为environment.ts，补全本地开发配置即可。

3. 校验开发服务配置 #

• 执行npx ng version查看本地Angular CLI版本，如果全局安装的CLI版本高于12.x，会出现构建配置兼容问题，直接在项目内执行npm install @angular/cli@12 --save-dev安装项目适配的本地CLI版本，后续启动、构建命令统一加npx前缀调用本地CLI，比如用npx ng serve启动，避免全局CLI版本不兼容的隐形错误。
• 启动时指定端口排除端口冲突问题：Angular CLI在部分Windows环境下不会主动抛出端口占用提示，服务看似启动成功实际没有正常监听，执行npx ng serve --port 4300指定不常用的端口启动，访问对应地址验证是否正常。
• 如果控制台出现静态资源404报错，检查angular.json中baseHref配置，如果配置为项目生产环境的子路径（比如/admin/），本地开发时会因为资源路径不对加载失败，启动时加--base-href /参数临时覆盖配置即可。

4. 兜底定位手段 #

• 执行npx ng build触发全量构建，ng serve的增量构建模式会跳过部分语法校验，很多隐形错误只会在全量构建时抛出，顺着构建报错点可以直接定位问题根源。
• 禁用浏览器所有广告拦截、脚本拦截类插件后重试，部分插件会误拦截Angular打包后的main.js文件，导致脚本不执行页面空白。

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