错误监控

Web SDK 实例化后，会根据 plugin.error、plugin.api 等配置在浏览器环境中自动安装对应监听逻辑。注意：只有创建 Aegis 实例后 SDK 才会开始监控；仅安装或导入 SDK 不会采集数据。

caution

Web SDK 依赖浏览器对象，SSR/SSG 框架中请仅在浏览器侧初始化。建议在初始化函数中增加 typeof window === 'undefined' 判断，或使用框架提供的客户端组件/客户端插件机制。

开启错误监控

import Aegis from 'bugly-web-sdk';

const aegis = new Aegis({
  id: '<bugly-app-id>',
  appKey: '<bugly-app-key>',
  buglyType: 'pro',
  plugin: {
    error: true,
    api: {
      reportWhenError: true,
      apiDetail: false,
    },
  },
});

专业版主流程只需配置 buglyType: 'pro'，SDK 会使用内置上报/白名单地址；一般用户不需要配置 hostUrl。

JS 执行错误

SDK 会通过浏览器全局错误事件捕获页面中的 JS 执行错误，并将错误信息和堆栈上报到后台。

对于部分前端框架，框架自身会接管组件渲染错误或生命周期错误。此时建议在框架错误钩子中主动调用 SDK 上报，避免错误被框架吞掉。

Vue 示例

Vue.config.errorHandler = function(err, vm, info) {
  aegis.error({
    msg: err.toString(),
    stack: err.stack,
    info: info,
  });
};

React 示例

import React from 'react';

class ErrorBoundary extends React.Component<any, { hasError: boolean }> {
  state = { hasError: false };

  static getDerivedStateFromError() {
    return { hasError: true };
  }

  componentDidCatch(error: Error, info: React.ErrorInfo) {
    aegis.error({
      msg: error.toString(),
      stack: error.stack,
      info: info.componentStack,
    });
  }

  render() {
    if (this.state.hasError) return null;
    return this.props.children;
  }
}

Promise 执行错误

SDK 会监听未被 catch 的 Promise 错误。为了页面健壮性，仍建议业务代码显式处理 Promise 异常，并在需要时补充业务上下文后主动上报。

async function loadData() {
  try {
    await requestData();
  } catch (error) {
    aegis.error({
      msg: 'loadData failed',
      error,
    });
    throw error;
  }
}

资源加载失败

页面元素发出的资源请求失败时，SDK 可通过浏览器错误事件捕获资源加载失败。常见资源包括：

<link> 标签请求的 CSS、font 等资源；
<script> 标签请求的脚本；
<img>、<audio>、<video> 标签请求的图片和多媒体资源。

如果业务使用自定义资源域名或代理层，建议同时检查跨域、缓存和资源 URL 归一化逻辑，避免错误归因不准确。

API 请求异常

开启 plugin.api 后，SDK 会拦截浏览器 fetch 和 XMLHttpRequest 请求，并在接口异常时上报 API 错误。常见异常包括：

HTTP status 大于等于 400；
请求超时、abort、跨域、cancel 等网络异常；
请求结束时 HTTP status 仍为 0；
业务返回码被 retCodeHandler 判定为异常。

new Aegis({
  id: '<bugly-app-id>',
  appKey: '<bugly-app-key>',
  plugin: {
    api: {
      reportWhenError: true,
      retCodeHandler(data) {
        try {
          if (typeof data === 'string') data = JSON.parse(data);
        } catch (e) {
          return { isErr: true, code: 'parse_error' };
        }

        return {
          isErr: data.code !== 0,
          code: String(data.code),
        };
      },
    },
  },
});

接口详情与敏感字段

SDK 不建议默认采集完整请求/响应详情。只有在定位问题确有需要时，再开启 apiDetail: true。开启后会收集请求参数、响应内容等详情；如包含密码、token、手机号、内部密钥等敏感字段，应通过 reqParamHandler、resBodyHandler、apiDetailReportUrls、apiDetailIgnoreUrls 等配置做脱敏或范围控制。

retcode 异常

接口业务返回码是否异常由 retCodeHandler 决定。如果没有配置自定义逻辑，SDK 会按内置逻辑尝试从响应体中识别返回码。不同业务接口的返回结构可能不同，建议接入时明确配置 retCodeHandler，统一错误判断口径。

new Aegis({
  id: '<bugly-app-id>',
  appKey: '<bugly-app-key>',
  plugin: {
    api: {
      retCodeHandler(data) {
        const ret = data?.retcode ?? data?.code ?? data?.ret ?? data?.errcode;
        return {
          isErr: String(ret) !== '0',
          code: String(ret ?? ''),
        };
      },
    },
  },
});

主动上报

自动采集之外，业务也可以在关键异常分支主动调用 aegis.error 补充上下文。例如捕获到框架错误、业务降级、初始化失败等自动监听难以覆盖的场景时，可主动上报更明确的错误信息。

try {
  await bootstrapApp();
} catch (error) {
  aegis.error({
    msg: 'bootstrapApp failed',
    error,
  });
}

错误监控

开启错误监控​

JS 执行错误​

Vue 示例​

React 示例​

Promise 执行错误​

资源加载失败​

API 请求异常​

retcode 异常​

主动上报​