一、引言

我们最近为线上商城增加了前端错误日志，当线上出现问题时，我们的前端监控群里就会收到消息。

很快我们就发现，错误各式各样，从"首页轮播图加载失败"到"用户收货地址格式错误"，各类错误混杂在一起，让人无从下手。

前端问题不止于此，我们可能会遇到各种类型的前端错误，从页面白屏到支付失败，从数据渲染异常到安全攻击尝试。这些错误对用户的影响程度各不相同，如果不加以区分地处理，不仅会浪费开发资源，还可能导致关键问题被忽视。

针对线上商城场景，我们需要的是一套完整的前端错误日志分级体系，能够自动捕获、分类和上报错误，根据错误严重程度进行差异化处理，并结合业务场景提供有针对性的解决方案。本文将基于React+JavaScript技术栈，深入探讨如何构建这样一套错误日志分级系统，分享我们在实际开发中遇到的典型问题及解决方案，帮助前端团队提升错误监控能力和问题排查效率。

二、错误日志分级规范

在线上商城环境中，不同功能的异常对业务的影响程度差异巨大。支付流程中断显然比一张图片加载失败要严重得多，因此需要对错误进行分级处理，以便团队能够优先解决最关键的问题。我们根据业务影响程度将前端错误分为四个等级：Critical（致命）、Error（错误）、Warning（警告）和Info（信息）。

2.1 商城关键场景错误分级

以下是针对线上商城的八大关键场景制定的错误分级标准：

表1：线上商城前端错误分级标准

2.2 分级依据与处理策略

我们的分级标准主要基于以下几个维度：

• 业务影响：是否影响核心交易流程、是否造成资金损失或用户数据丢失。
• 影响范围：受影响用户比例、功能模块的重要性。
• 恢复难度：问题是否可自动恢复，是否需要人工干预。
• 安全风险：是否涉及安全漏洞或攻击行为。

基于以上标准，我们制定了不同级别错误的处理策略：

• Critical级别：立即通知相关人员，自动创建高优先级工单，24/7即时告警。
• Error级别：30分钟内创建中等优先级工单，工作日工作时间通知。
• Warning级别：每日汇总报告，定期分析优化。
• ∙nfo级别：记录日志，用于后续分析优化。

三、日志工具设计与实现

3.1 日志工具封装

为了实现统一的日志管理，我们封装了一个完整的Logger类，支持不同级别的日志输出、环境自适应和远程上报功能：

/**
 * Logger 类用于统一管理前端日志输出和上报逻辑。
 * 支持不同日志级别（DEBUG/INFO/WARN/ERROR/FATAL）的控制台输出与远程上报。
 */
class Logger {
  /**
   * 日志级别枚举，值越小优先级越高
   */
  static levels = {
    DEBUG: 0,
    INFO: 1,
    WARN: 2,
    ERROR: 3,
    FATAL: 4,
  };

  /**
   * 当前设置的日志级别，默认为 DEBUG
   */
  static level = Logger.levels.DEBUG;

  /**
   * 模块名称，用于标识日志来源模块
   */
  static moduleName = '';

  /**
   * 初始化日志配置
   * @param {Object} config - 配置对象
   * @param {number} [config.level=Logger.levels.DEBUG] - 设置日志级别
   * @param {string} [config.moduleName=''] - 设置模块名称
   * @param {string} [config.reportURL='/api/logs'] - 设置日志上报地址
   */
  static init(config = {}) {
    this.level = config.level || this.levels.DEBUG;
    this.moduleName = config.moduleName || '';
    this.reportURL = config.reportURL || '/api/logs';
  }

  /**
   * 核心日志记录方法，根据日志级别决定是否输出和上报
   * @param {number} level - 日志级别
   * @param {string} message - 日志消息内容
   * @param {Error|null} [error=null] - 错误对象（可选）
   * @param {Object} [extra={}] - 附加信息（可选）
   */
  static log(level, message, error = null, extra = {}) {
    // 如果当前日志级别低于设定级别，则不处理
    if (level < this.level) return;

    const timestamp = new Date().toISOString();
    const logEntry = {
      timestamp,
      level: Object.keys(this.levels).find(key => this.levels[key] === level),
      module: this.moduleName,
      message,
      error: error
        ? {
            message: error.message,
            stack: error.stack,
          }
        : null,
      ...extra,
    };

    // 构造格式化的控制台输出字符串
    const formattedMessage = `[${timestamp}] [${logEntry.level}] [${
      this.moduleName
    }] - ${message}${error ? ` - Error: ${error.message}` : ''}`;

    // 根据日志级别选择不同的控制台输出方式
    switch (level) {
      case this.levels.DEBUG:
        console.debug(formattedMessage);
        break;
      case this.levels.INFO:
        console.info(formattedMessage);
        break;
      case this.levels.WARN:
        console.warn(formattedMessage);
        break;
      case this.levels.ERROR:
      case this.levels.FATAL:
        console.error(formattedMessage);
        break;
    }

    // 在生产环境中，对于警告及以上级别的日志进行远程上报
    if (process.env.NODE_ENV === 'production' && level >= this.levels.WARN) {
      this.report(logEntry);
    }
  }

  /**
   * 将日志条目通过 sendBeacon 或 fetch 上报到服务器
   * @param {Object} logEntry - 要上报的日志对象
   */
  static report(logEntry) {
    const data = JSON.stringify(logEntry);
    // 使用 navigator.sendBeacon 提高上报可靠性
    if (navigator.sendBeacon) {
      navigator.sendBeacon(this.reportURL, data);
    } else {
      // 兼容性降级使用 fetch，并在失败时存储到本地
      fetch(this.reportURL, {
        method: 'POST',
        body: data,
        headers: { 'Content-Type': 'application/json' },
        keepalive: true,
      }).catch(() => {
        this.storeLocally(logEntry);
      });
    }
  }

  /**
   * 输出 DEBUG 级别日志
   * @param {string} message - 日志消息
   * @param {Object} [extra={}] - 附加信息
   */
  static debug(message, extra = {}) {
    this.log(this.levels.DEBUG, message, null, extra);
  }

  /**
   * 输出 INFO 级别日志
   * @param {string} message - 日志消息
   * @param {Object} [extra={}] - 附加信息
   */
  static info(message, extra = {}) {
    this.log(this.levels.INFO, message, null, extra);
  }

  /**
   * 输出 WARN 级别日志
   * @param {string} message - 日志消息
   * @param {Error|null} [error=null] - 错误对象
   * @param {Object} [extra={}] - 附加信息
   */
  static warn(message, error = null, extra = {}) {
    this.log(this.levels.WARN, message, error, extra);
  }

  /**
   * 输出 ERROR 级别日志
   * @param {string} message - 日志消息
   * @param {Error|null} [error=null] - 错误对象
   * @param {Object} [extra={}] - 附加信息
   */
  static error(message, error = null, extra = {}) {
    this.log(this.levels.ERROR, message, error, extra);
  }

  /**
   * 输出 FATAL 级别日志
   * @param {string} message - 日志消息
   * @param {Error|null} [error=null] - 错误对象
   * @param {Object} [extra={}] - 附加信息
   */
  static fatal(message, error = null, extra = {}) {
    this.log(this.levels.FATAL, message, error, extra);
  }
}

1、设计思路与重点逻辑：

• 环境自适应：开发环境输出详细DEBUG日志，生产环境只上报WARN级别以上日志，兼顾开发调试和生产性能。
• 远程上报优化：使用navigator.sendBeacon方法实现可靠上报，避免传统AJAX请求在页面卸载时被取消的问题。
• 降级策略：当上报失败时，日志会降级存储到本地Storage，待下次恢复后重新上报。
• 结构化日志：所有日志统一格式，包含时间戳、级别、模块、消息和错误信息，便于解析分析。

2、参数解析：

• level：日志级别，对应内部levels枚举值。
• message：日志描述信息，应简洁明确。
• error：可选Error对象，包含堆栈信息用于排查。
• extra：扩展字段，可包含用户ID、页面路由等上下文信息。

3.2 错误捕获机制

仅仅有日志工具类还不够，我们需要在全应用范围捕获各种类型的错误。以下是基于React的全局错误捕获机制：

/**
 * React错误边界组件，用于捕获子组件树中的JavaScript错误，
 * 并展示降级UI而不是崩溃整个应用。
 * 
 * @param {Object} props - 组件属性
 * @param {ReactNode} props.children - 被包裹的子组件
 * @param {ReactNode} [props.fallback] - 发生错误时显示的降级UI
 * @param {boolean} [props.critical] - 是否为关键组件，决定是否上报致命错误
 * @param {string} [props.componentName] - 组件名称，用于错误上报
 */
class ErrorBoundary extends React.Component {
  constructor(props) {
    super(props);
    this.state = { hasError: false };
  }

  /**
   * 静态方法，在渲染阶段捕获错误并更新state，
   * 用于在错误发生后更新UI。
   * 
   * @param {Error} error - 捕获到的错误对象
   * @returns {Object} 返回新的state对象，设置hasError为true
   */
  static getDerivedStateFromError(error) {
    return { hasError: true };
  }

  /**
   * 在提交阶段调用，用于记录错误信息和上报错误。
   * 
   * @param {Error} error - 捕获到的错误对象
   * @param {Object} errorInfo - 包含组件堆栈信息的对象
   */
  componentDidCatch(error, errorInfo) {
    // 记录组件堆栈信息
    Logger.error('React组件错误', error, {
      componentStack: errorInfo.componentStack,
      page: window.location.pathname,
    });

    // 上报错误
    if (this.props.critical) {
      Logger.fatal('关键组件渲染失败', error, {
        component: this.props.componentName,
      });
    }
  }

  /**
   * 渲染方法，根据是否有错误决定渲染子组件还是降级UI。
   * 
   * @returns {ReactNode} 子组件或降级UI
   */
  render() {
    if (this.state.hasError) {
      return this.props.fallback || <div>页面渲染出错，请刷新尝试</div>;
    }

    return this.props.children;
  }
}

/**
 * 设置全局错误处理机制，包括：
 * 1. 全局JS运行时错误捕获
 * 2. 未处理的Promise拒绝事件捕获
 * 3. 网络请求错误拦截
 */
const setupErrorHandling = () => {
  // 捕获全局JS错误
  window.addEventListener('error', event => {
    Logger.error(`全局错误: ${event.message}`, event.error, {
      filename: event.filename,
      lineno: event.lineno,
      colno: event.colno,
    });
    return true;
  });

  // 捕获未处理的Promise拒绝
  window.addEventListener('unhandledrejection', event => {
    Logger.warn('未处理的Promise拒绝', event.reason, {
      type: 'unhandledrejection',
    });
    event.preventDefault();
  });

  // 捕获网络请求错误
  const originalFetch = window.fetch;
  window.fetch = async (...args) => {
    try {
      const response = await originalFetch(...args);
      if (!response.ok) {
        Logger.error(
          `API请求失败: ${response.status} ${response.statusText}`,
          null,
          {
            url: args[0],
            status: response.status,
            method: args[1]?.method || 'GET',
          },
        );
      }
      return response;
    } catch (error) {
      Logger.error('网络请求异常', error, { url: args[0] });
      throw error;
    }
  };
};

1、架构解析：

上述代码实现了三层错误捕获机制：

• React组件层：通过ErrorBoundary捕获组件渲染错误。
• 全局JavaScript层：通过window.addEventListener('error')捕获全局JS错误。
• 网络请求层：通过fetch拦截捕获网络请求异常。

3.3 日志收集系统架构

完整的日志收集系统不仅包括前端SDK，还需要考虑后端接收、存储和展示环节。下图展示了整体架构：

四、问题排查与修复实战

4.1 案例一：支付流程中断问题

问题现象：用户点击支付按钮后，页面长时间加载最终显示"网络超时"，但网络连接正常。

技术环境：React 18 + React Router 6，支付网关为支付宝和微信支付集成。

排查步骤：

• 查看日志平台：筛选支付相关Error级别以上日志，发现多条"支付网关请求超时"错误。
• 分析用户操作路径：通过用户会话回溯功能，发现用户从点击支付到出现超时平均耗时超过30秒
• 检查网络请求：发现支付前置校验接口（/api/payment/validate）响应缓慢。
• 追踪性能数据：使用Performance API检测支付流程各阶段耗时。

性能检测代码：

const measurePaymentPerformance = async () => {
  // 性能度量标记
  performance.mark('payment-start');
  
  try {
    // 阶段1: 支付前置校验
    performance.mark('validate-start');
    await validatePayment();
    performance.mark('validate-end');
    performance.measure('validate', 'validate-start', 'validate-end');
    
    // 阶段2: 支付网关调用
    performance.mark('gateway-start');
    const result = await callPaymentGateway();
    performance.mark('gateway-end');
    performance.measure('gateway', 'gateway-start', 'gateway-end');
    
    // 阶段3: 订单状态更新
    performance.mark('order-update-start');
    await updateOrderStatus();
    performance.mark('order-update-end');
    performance.measure('order-update', 'order-update-start', 'order-update-end');
    
    Logger.info('支付流程性能数据', {
      validate: performance.getEntriesByName('validate')[0].duration,
      gateway: performance.getEntriesByName('gateway')[0].duration,
      orderUpdate: performance.getEntriesByName('order-update')[0].duration,
      total: performance.getEntriesByName('payment-start')[0].duration
    });
    
    return result;
  } catch (error) {
    Logger.error('支付流程执行失败', error, {
      validate: performance.getEntriesByName('validate')[0]?.duration,
      gateway: performance.getEntriesByName('gateway')[0]?.duration,
      stage: getErrorStage(error)
    });
    throw error;
  }
};

根本原因分析：通过性能度量发现支付前置校验接口耗时异常（平均超过5秒），进一步排查发现是由于校验接口中查询用户优惠券的SQL语句没有索引，导致数据库查询缓慢。

解决方案：

• 前端优化：增加支付流程超时控制，避免用户长时间等待

// 支付请求超时控制
const callWithTimeout = (promise, timeout, errorMessage) => {
  return Promise.race([
    promise,
    new Promise((_, reject) => 
      setTimeout(() => reject(new Error(errorMessage)), timeout)
    )
  ]);
};

// 支付流程调用
try {
  const paymentResult = await callWithTimeout(
    measurePaymentPerformance(),
    15000, // 15秒超时
    '支付请求超时，请稍后重试'
  );
  Logger.info('支付成功', { result: paymentResult });
} catch (error) {
  if (error.message.includes('超时')) {
    Logger.warn('支付流程超时', error, { timeout: 15000 });
    // 显示友好错误提示
    showToast('支付请求超时，请检查网络后重试');
  } else {
    Logger.error('支付失败', error);
    throw error;
  }
}

• 后端配合：优化数据库查询，增加索引，缓存用户优惠券信息。
• 降级方案：当支付主流程异常时，提供备用支付通道。

避坑总结：

• 前端需要设置合理的超时时间并提供用户友好提示。
• 关键业务流程需要记录详细的性能数据以便排查问题。
• 与后端协作建立端到端的性能监控体系。

4.2 案例二：商品详情页白屏问题

问题现象：部分用户访问商品详情页时出现白屏，控制台报"Cannot read properties of undefined"错误。

技术环境：React 18 + Redux Toolkit + React Router 6。

排查步骤：

• 查看错误堆栈：通过日志平台找到错误堆栈信息，定位到组件渲染过程中访问product.detail.price时出错
• 数据分析：发现出现问题的用户大多使用旧版本APP或低速网络
• 复现路径：尝试在弱网环境下复现问题，发现数据加载不完全时组件直接访问嵌套属性导致错误

根本原因：组件没有正确处理API返回的数据结构，当数据加载不完全或API返回异常数据时，直接访问深层属性导致JavaScript运行时错误。

解决方案：

• 增加错误边界：使用ErrorBoundary包裹商品详情组件，防止整个页面白屏

// 商品详情页组件
const ProductDetailPage = () => {
  return (
    <ErrorBoundary 
      fallback={<ProductDetailErrorView />}
      critical={true}
      componentName="ProductDetailPage"
    >
      <ProductDetailContainer />
    </ErrorBoundary>
  );
};

// 商品详情错误视图
const ProductDetailErrorView = () => {
  return (
    <div className="error-view">
      <h3>页面加载失败</h3>
      <p>商品信息加载异常，请重试</p>
      <button onClick={() => window.location.reload()}>重新加载</button>
    </div>
  );
};

• 完善数据校验：增加接口数据校验和默认值处理

// 商品数据校验函数
const validateProductData = (product) => {
  if (!product || typeof product !== 'object') {
    Logger.warn('商品数据无效', null, { product });
    return false;
  }
  
  const requiredFields = ['id', 'name', 'price', 'stock'];
  for (const field of requiredFields) {
    if (!(field in product)) {
      Logger.error('商品数据缺少必要字段', null, { 
        field, 
        product 
      });
      return false;
    }
  }
  
  return true;
};

// 安全访问商品信息
const getProductPrice = (product) => {
  try {
    // 使用可选链和空值合并
    return product?.detail?.price ?? product?.basePrice ?? 0;
  } catch (error) {
    Logger.warn('获取商品价格失败', error, { product });
    return 0;
  }
};

• 增强加载状态：优化数据加载中的用户体验

// 增强版商品详情组件
const EnhancedProductDetail = ({ productId }) => {
  const [product, setProduct] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);
  
  useEffect(() => {
    const fetchProduct = async () => {
      try {
        setLoading(true);
        const productData = await ProductAPI.getDetail(productId);
        
        if (!validateProductData(productData)) {
          throw new Error('Invalid product data');
        }
        
        setProduct(productData);
        Logger.info('商品数据加载成功', null, { productId });
      } catch (err) {
        Logger.error('商品数据加载失败', err, { productId });
        setError(err.message);
      } finally {
        setLoading(false);
      }
    };
    
    fetchProduct();
  }, [productId]);
  
  if (loading) {
    return <ProductDetailSkeleton />;
  }
  
  if (error) {
    return <ProductDetailErrorView error={error} />;
  }
  
  return <ProductDetailContent product={product} />;
};

避坑总结：

• 始终对API返回数据进行校验和防御性处理。
• 使用可选链操作符（?.）和空值合并操作符（??）安全访问嵌套属性。
• 为关键组件添加错误边界，防止局部错误导致整个应用崩溃。
• 提供适当的加载状态和错误反馈，增强用户体验。

五、避坑总结与最佳实践

在前端错误监控与处理实践中，我们积累了大量经验教训。以下是一些关键的最佳实践和避坑指南：

5.1 日志记录常见问题与规避

表2：日志记录中的常见问题及解决方案

5.2 性能与用户体验平衡

前端错误监控本身也会消耗资源，需要在监控详细程度和性能影响之间找到平衡：

• 采样上报：对高频非关键错误进行采样上报，避免数据过载

// 采样率配置
const SamplingConfig = {
  ERROR: 1.0,    // 错误级别100%上报
  WARN: 0.5,     // 警告级别50%采样
  INFO: 0.1,     // 信息级别10%采样
  DEBUG: 0.01    // 调试级别1%采样
};

// 采样上报函数
const reportWithSampling = (logEntry) => {
  const samplingRate = SamplingConfig[logEntry.level] || 0.1;
  if (Math.random() < samplingRate) {
    Logger.report(logEntry);
  }
};

• 批量上报：将多条日志合并为一次请求，减少网络开销

// 批量上报队列
let batchQueue = [];
let batchTimer = null;

const addToBatch = (logEntry) => {
  batchQueue.push(logEntry);
  
  if (batchQueue.length >= 10) {
    // 达到10条立即发送
    flushBatch();
  } else if (!batchTimer) {
    // 30秒内不足10条则定时发送
    batchTimer = setTimeout(flushBatch, 30000);
  }
};

const flushBatch = () => {
  if (batchQueue.length === 0) return;
  
  const batchData = JSON.stringify(batchQueue);
  navigator.sendBeacon('/api/logs/batch', batchData);
  
  // 清空队列和计时器
  batchQueue = [];
  clearTimeout(batchTimer);
  batchTimer = null;
};

• 日志压缩：使用gzip压缩日志数据，减少传输体积

5.3 错误预警与通知机制

建立分级的错误预警机制，确保不同级别错误得到适当处理：

• 即时告警：Critical级别错误实时通知相关人员

// 告警通知函数
const sendAlert = (logEntry) => {
  if (logEntry.level === 'CRITICAL') {
    // 多种通知渠道
    sendEmailAlert(logEntry);
    sendSMSAlert(logEntry);
    sendDingTalkAlert(logEntry);
  } else if (logEntry.level === 'ERROR') {
    // 仅邮件通知
    sendEmailAlert(logEntry);
  }
  
  // 记录告警历史
  Logger.info('已发送告警通知', null, {
    alert: logEntry.level,
    message: logEntry.message,
    timestamp: new Date().toISOString()
  });
};

• 每日报告：汇总所有错误和警告，每日发送报告邮件
• 趋势监控：监控错误率变化趋势，提前发现系统性问题

5.4 安全与隐私保护

在前端日志记录中，必须特别注意用户隐私和数据安全：

• 敏感信息过滤：避免记录敏感数据到日志中

// 敏感字段过滤
const filterSensitiveData = (data) => {
  const sensitiveFields = [
    'password', 'token', 'creditCard', 
    'cvv', 'phone', 'email'
  ];
  
  const filtered = { ...data };
  for (const field of sensitiveFields) {
    if (field in filtered) {
      filtered[field] = '***REDACTED***';
    }
  }
  
  return filtered;
};

// 使用示例
Logger.info('用户登录成功', null, {
  user: filterSensitiveData(userData),
  context: 'auth'
});

• 合规性考虑：遵守GDPR、CCPA等数据保护法规
• 访问控制：对日志数据实施严格的访问控制策略

六、结语

线上商城前端错误日志分级实践，本质是建立"以用户为中心"的监控思维——不再追求"零错误"的理想状态，而是确保每个错误都能得到与其业务影响相匹配的关注与处理。

本文从业务场景出发，结合代码实现与真实案例，提供了以下核心收获：

• 错误分级是基础：根据业务影响程度将错误分为Critical、Error、Warning和Info四个级别，确保优先处理关键问题。
• 工具封装是保障：设计完善的Logger工具类，实现环境自适应、远程上报和降级策略。
• 全链路监控是关键：通过ErrorBoundary、全局错误捕获和网络请求拦截实现全链路错误监控。
• 排查方法论是核心：结合性能监控、用户行为回溯和日志分析，快速定位问题根源。
• 性能与安全是必须：平衡监控详细程度与性能影响，注重用户隐私和数据安全。

通过本文阐述的分级标准、技术架构与实践经验，团队可构建精准、高效的错误监控体系，将有限的技术资源聚焦于真正影响用户体验的核心问题，最终实现"降本增效"与"用户满意度提升"的双重目标。

通过实施本文介绍的日志分级体系和错误监控实践，前端开发团队可以更加高效地排查和解决问题，提升应用稳定性和用户体验。