Angular站点通过GTM部署Clarity后100%会话JS错误的调试方法

一、优先解决“script error”（占比98%） #

“script error”大多是浏览器同源策略导致的跨域脚本错误掩盖，按以下步骤排查：

• 给Clarity脚本添加跨域属性：如果通过GTM加载Clarity的CDN脚本，在GTM的标签配置里，给<script>标签添加crossorigin="anonymous"属性。这能让浏览器允许跨域脚本的错误详情被正常捕获，而不是被隐藏成模糊的“script error”。
• 启用Chrome跨域错误详情：打开Chrome DevTools → 点击右上角设置图标（F1）→ 找到“Experiments”面板，勾选“Show CORS errors in console”；或者在控制台执行localStorage.setItem('devtools:experiments:show-cors-error-details', true)，重启DevTools后即可看到跨域错误的具体信息。

二、Angular专属错误调试 #

• 开启Angular详细错误日志：在开发环境的environment.ts中设置enableDebugTools: true、production: false，让Angular输出完整的错误栈和上下文信息。生产环境如需调试，可临时开启，但上线前务必关闭。
• 自定义全局错误捕获：创建Angular自定义ErrorHandler，捕获所有未处理错误并打印完整栈信息，避免被Clarity/GTM模糊处理：

import { ErrorHandler, Injectable } from '@angular/core';

@Injectable()
export class CustomErrorHandler implements ErrorHandler {
  handleError(error: any): void {
    console.error('全局未处理错误:', error);
    console.error('错误调用栈:', error.stack);
    // 可选：将错误上报到自有日志系统
  }
}

在AppModule的providers中替换默认处理：

providers: [
  { provide: ErrorHandler, useClass: CustomErrorHandler }
]

三、GTM部署逻辑排查 #

• 调整Clarity标签触发时机：如果Clarity脚本在Angular初始化前加载，会捕获到Angular启动阶段的未定义函数/空属性错误。将GTM中Clarity标签的触发条件改为“DOM Ready”或“Window Loaded”，确保Angular核心脚本已加载完成。
• GTM预览模式验证：开启GTM预览模式，查看Clarity脚本的加载顺序，检查是否与其他监控标签（如GA）存在资源竞争或冲突，导致脚本执行异常。

四、生产环境错误定位 #

• 上传源映射文件：Angular生产环境默认压缩代码，错误栈是混淆的。部署时同步上传生成的.js.map源映射文件到服务器，Clarity会自动关联映射，将压缩后的错误栈还原为原始代码的行号和函数名。
• 利用Clarity会话重放：虽然每个错误场景不同，但通过Clarity的会话重放功能，定位错误发生的时间点，还原用户的操作路径（如点击、输入、页面跳转），再在本地模拟相同操作重现错误。

五、其他排查方向 #

• 浏览器兼容性检查：确认用户使用的浏览器是否在Clarity和Angular的支持范围内（如旧版IE可能缺失必要API），必要时添加对应的polyfill。
• 第三方依赖排查：逐个禁用项目中的第三方组件/插件，验证是否是某个依赖加载或执行时触发的错误，被Clarity捕获。

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