全栈进阶指南

皮肤切换

前端错误收集 SDK 详细开发排期任务 ​

目标版本：v1.0.0
发布日期：2025年12月31日技术栈：TypeScript + Monorepo(pnpm) + Vite + Jest

总体开发节奏 ​

阶段时间范围目标
Phase 1: 核心架构搭建2025-11-04 ~ 2025-11-10Monorepo 结构、核心包基础架构、错误捕获机制
Phase 2: 浏览器适配与上报2025-11-11 ~ 2025-11-17浏览器环境适配、错误上报机制、上下文收集
Phase 3: 框架集成与插件系统2025-11-18 ~ 2025-11-24React/Vue 集成、插件系统、Source Map 支持
Phase 4: 测试与优化2025-11-25 ~ 2025-12-01单元测试、性能优化、兼容性测试
Phase 5: 文档与发布2025-12-02 ~ 2025-12-08文档完善、Demo 示例、发布准备
Phase 6: 预发布与修复2025-12-09 ~ 2025-12-15预发布测试、Bug 修复、最终审核
Phase 7: 正式发布2025-12-16 ~ 2025-12-31正式发布 v1.0.0、发布公告、后续规划

Phase 1: 核心架构搭建（2025-11-04 ~ 2025-11-10） ​

目标

  • 初始化 Monorepo 项目结构
  • 创建核心包 [core]，实现基础错误处理逻辑
  • 定义全局类型和接口

任务列表

任务描述负责人状态截止
[P1-T1] 初始化 Monorepo 项目使用 pnpm 创建 Monorepo 结构，配置 workspace@Nil🟢 已完成2025-11-04
[P1-T2] 创建 packages 结构创建 core、types、utils 包目录结构@Nil🟢 已完成2025-11-04
[P1-T3] 配置 TypeScript 环境配置 tsconfig.json，设置路径映射@Nil🟢 已完成2025-11-05
[P1-T4] 定义全局类型在 types 包中定义 SDKOptions、ErrorEvent 等核心接口@Nil🟢 已完成2025-11-05
[P1-T5] 实现核心错误处理逻辑在 core 包中实现 setupGlobalErrorHandler 基础逻辑@Nil🟢 已完成2025-11-06
[P1-T6] 实现错误上报机制实现 sendReport 基础功能，支持 sendBeacon 和 fetch@Nil🟢 已完成2025-11-07
[P1-T7] 创建工具函数在 utils 包中实现防抖、节流、序列化等工具函数@Nil🟢 已完成2025-11-08
[P1-T8] 实现 SDK 初始化实现 init 函数，支持基本配置@Nil🟢 已完成2025-11-09
[P1-T9] 添加构建配置配置 Vite 构建脚本，支持多格式输出@Nil🟢 已完成2025-11-10
[P1-T10] Phase 1 内部评审演示基础错误捕获和上报功能@Nil🟢 已完成2025-11-10

Phase 2: 浏览器适配与上报（2025-11-11 ~ 2025-11-17） ​

目标

  • 完善浏览器环境下的错误捕获机制
  • 实现完整的上下文信息收集
  • 优化错误上报策略

任务列表

任务描述负责人状态截止
[P2-T1] 创建 browser 包创建浏览器环境适配包@Nil🔵 待开始2025-11-11
[P2-T2] 实现资源加载错误捕获捕获 script、img 等资源加载失败错误@Nil🔵 待开始2025-11-12
[P2-T3] 实现上下文信息收集收集用户信息、设备信息、页面信息等@Nil🔵 待开始2025-11-13
[P2-T4] 实现性能指标收集通过 Performance API 收集 FP、LCP、FID 等指标@Nil🔵 待开始2025-11-14
[P2-T5] 优化上报策略实现节流、防抖、队列缓存等功能@Nil🔵 待开始2025-11-15
[P2-T6] 实现采样率控制支持配置采样率，减少上报量@Nil🔵 待开始2025-11-16
[P2-T7] 添加 beforeSend 钩子支持在上报前修改或过滤事件@Nil🔵 待开始2025-11-17
[P2-T8] Phase 2 内部评审演示完整的浏览器环境下错误收集和上报功能@Nil🔵 待开始2025-11-17

Phase 3: 框架集成与插件系统（2025-11-18 ~ 2025-11-24） ​

目标

  • 实现主流前端框架集成
  • 开发插件系统
  • 支持 Source Map 解析

任务列表

任务描述负责人状态截止
[P3-T1] 创建 react 包实现 React 错误边界集成@Nil🔵 待开始2025-11-18
[P3-T2] 创建 vue 包实现 Vue 全局错误处理器集成@Nil🔵 待开始2025-11-19
[P3-T3] 设计插件系统架构定义 Plugin 接口，实现插件注册机制@Nil🔵 待开始2025-11-20
[P3-T4] 实现用户行为插件实现用户行为追踪插件（点击、路由变化等）@Nil🔵 待开始2025-11-21
[P3-T5] 实现 Source Map 插件支持 Source Map 解析，定位原始错误位置@Nil🔵 待开始2025-11-22
[P3-T6] 实现 Console 捕获插件可选地捕获 console.error 输出@Nil🔵 待开始2025-11-23
[P3-T7] 插件系统集成测试测试多个插件协同工作@Nil🔵 待开始2025-11-24
[P3-T8] Phase 3 内部评审演示框架集成和插件系统功能@Nil🔵 待开始2025-11-24

Phase 4: 测试与优化（2025-11-25 ~ 2025-12-01） ​

目标

  • 完善单元测试和集成测试
  • 进行性能优化
  • 完成兼容性测试

任务列表

任务描述负责人状态截止
[P4-T1] 编写 core 包单元测试使用 Jest 编写核心功能测试@Nil🔵 待开始2025-11-25
[P4-T2] 编写 browser 包单元测试测试浏览器环境适配功能@Nil🔵 待开始2025-11-26
[P4-T3] 编写插件系统测试测试各类插件功能@Nil🔵 待开始2025-11-27
[P4-T4] 编写集成测试使用 Playwright 进行端到端测试@Nil🔵 待开始2025-11-28
[P4-T5] 性能优化优化 SDK 启动性能，减少内存占用@Nil🔵 待开始2025-11-29
[P4-T6] 兼容性测试在多浏览器环境下测试 SDK 功能@Nil🔵 待开始2025-11-30
[P4-T7] 类型测试使用 dtslint 验证类型定义正确性@Nil🔵 待开始2025-12-01
[P4-T8] Phase 4 内部评审演示测试结果和性能优化效果@Nil🔵 待开始2025-12-01

Phase 5: 文档与发布（2025-12-02 ~ 2025-12-08） ​

目标

  • 完善各包的文档和示例
  • 创建 Demo 应用
  • 准备发布材料

任务列表

任务描述负责人状态截止
[P5-T1] 编写 core 包文档编写详细的 API 文档和使用说明@Nil🔵 待开始2025-12-02
[P5-T2] 编写框架集成包文档编写 React/Vue 集成使用说明@Nil🔵 待开始2025-12-03
[P5-T3] 编写插件系统文档编写插件开发指南和使用说明@Nil🔵 待开始2025-12-04
[P5-T4] 创建 Demo 应用创建完整的示例应用展示各项功能@Nil🔵 待开始2025-12-05
[P5-T5] 编写 README 和指南编写主 README 和快速开始指南@Nil🔵 待开始2025-12-06
[P5-T6] 配置发布流程配置 Changesets 和自动化发布流程@Nil🔵 待开始2025-12-07
[P5-T7] 代码审查和质量检查进行全面的代码审查和质量检查@Nil🔵 待开始2025-12-08
[P5-T8] Phase 5 内部评审演示完整文档和 Demo 应用@Nil🔵 待开始2025-12-08

Phase 6: 预发布与修复（2025-12-09 ~ 2025-12-15） ​

目标

  • 进行预发布测试
  • 修复发现的问题
  • 完成最终审核

任务列表

任务描述负责人状态截止
[P6-T1] 预发布版本打包打包预发布版本，准备测试环境@Nil🔵 待开始2025-12-09
[P6-T2] 内部测试团队内部进行全面测试@Nil🔵 待开始2025-12-10
[P6-T3] Bug 修复修复测试中发现的问题@Nil🔵 待开始2025-12-12
[P6-T4] 安全审计进行安全和隐私合规性检查@Nil🔵 待开始2025-12-13
[P6-T5] 性能基准测试进行最终性能基准测试@Nil🔵 待开始2025-12-14
[P6-T6] 最终审核进行最终代码和文档审核@Nil🔵 待开始2025-12-15
[P6-T7] 准备发布公告编写发布公告和更新日志@Nil🔵 待开始2025-12-15

Phase 7: 正式发布（2025-12-16 ~ 2025-12-31） ​

目标

  • 正式发布 v1.0.0 版本
  • 发布公告和推广
  • 规划后续迭代

任务列表

任务描述负责人状态截止
[P7-T1] 发布到 npm使用 Changesets 发布 v1.0.0 到 npm@Nil🔵 待开始2025-12-16
[P7-T2] 发布公告在社交媒体和技术社区发布公告@Nil🔵 待开始2025-12-17
[P7-T3] 收集反馈收集早期用户的反馈和建议@Nil🔵 待开始2025-12-20
[P7-T4] 规划 v1.1 版本根据反馈规划下一版本功能@Nil🔵 待开始2025-12-25
[P7-T5] 创建 GitHub Wiki创建详细的 Wiki 文档@Nil🔵 待开始2025-12-28
[P7-T6] 技术总结编写项目技术总结报告@Nil🔵 待开始2025-12-30
[P7-T7] 项目归档归档项目资料和文档@Nil🔵 待开始2025-12-31

后续迭代路线图（v1.1+） ​

版本计划内容
v1.1支持更多框架集成（Angular、Svelte等）、增强插件系统
v1.2实现错误聚类分析、智能告警功能
v1.3支持移动端错误收集、React Native 集成
v2.0重构核心架构、支持 WebAssembly 加速、可视化监控面板

附录：关键依赖清单（package.json snippet） ​

json
{
  "dependencies": {
    "typescript": "^5.0.0",
    "tslib": "^2.6.0"
  },
  "devDependencies": {
    "vite": "^5.0.0",
    "jest": "^29.0.0",
    "playwright": "^1.40.0",
    "@types/jest": "^29.0.0",
    "dtslint": "^4.2.0"
  }
}

附录：SDK 架构 ​

text
packages/
├── oath-error/
│   ├── core/                  # 核心逻辑：错误捕获、上下文管理、上报机制
│   ├── browser/               # 浏览器环境适配层
│   ├── react/                 # React 错误边界集成
│   ├── vue/                   # Vue 全局错误处理器集成
│   ├── utils/                 # 公共工具函数
│   ├── types/                 # 全局类型定义
│   ├── plugin-source-map/     # Source Map 解析插件
│   ├── plugin-user-behavior/  # 用户行为追踪插件
│   └── demo/                  # 示例应用
├── docs/                      # 文档
├── tests/                     # 测试文件
└── package.json               # Monorepo 根配置

核心模块设计 ​

错误捕获机制 ​

packages/core/src/errorHandler.ts ​

ts
export function setupGlobalErrorHandler() {
  window.onerror = (message, source, lineno, colno, error) => {
    reportError({
      type: 'runtime',
      message,
      stack: error?.stack,
      filename: source,
      line: lineno,
      column: colno,
      timestamp: Date.now(),
    });
    return true;
  };

  window.addEventListener('unhandledrejection', (event) => {
    reportError({
      type: 'promise',
      message: event.reason?.message || String(event.reason),
      stack: event.reason?.stack,
      timestamp: Date.now(),
    });
  });
}

packages/types/index.ts ​

ts
export interface SDKOptions {
  appId: string;
  reportUrl: string;
  sampleRate?: number;
  beforeSend?: (event: ErrorEvent) => ErrorEvent | null;
  plugins?: Plugin[];
}

export interface ErrorEvent {
  message: string;
  stack?: string;
  type: 'runtime' | 'promise' | 'resource';
  context: {
    url: string;
    userAgent: string;
    timestamp: number;
    performance?: Record<string, number>;
    custom?: Record<string, any>;
  };
}

packages/core/src/index.ts ​

ts
import { setupGlobalErrorHandler } from './errorHandler';
import { sendReport } from './reporter';

let initialized = false;

export function init(options: SDKOptions) {
  if (initialized) {
    console.warn('SDK already initialized');
    return;
  }

  // 设置全局错误处理器
  setupGlobalErrorHandler();
  
  // 初始化插件
  if (options.plugins) {
    options.plugins.forEach(plugin => {
      plugin.init?.({ options, report: sendReport });
    });
  }

  initialized = true;
  console.log('Error SDK initialized');
}

上报机制 ​

packages/core/src/reporter.ts ​

ts
export function sendReport(data: ErrorEvent) {
  // beforeSend 钩子
  if (options.beforeSend) {
    const modifiedData = options.beforeSend(data);
    if (!modifiedData) return; // 如果返回 null 则取消上报
    data = modifiedData;
  }

  // 采样率控制
  if (options.sampleRate && Math.random() > options.sampleRate) {
    return;
  }

  // 发送上报
  if (navigator.sendBeacon) {
    navigator.sendBeacon(options.reportUrl, new Blob([JSON.stringify(data)], { type: 'application/json' }));
  } else {
    fetch(options.reportUrl, {
      method: 'POST',
      body: JSON.stringify(data),
      keepalive: true,
      headers: { 'Content-Type': 'application/json' }
    }).catch(() => {
      // fallback 处理
    });
  }
}

插件系统 ​

packages/types/plugin.ts ​

ts
export interface Plugin {
  name: string;
  init?: (sdk: SDK) => void;
  beforeReport?: (event: ErrorEvent) => ErrorEvent | null;
}

export interface SDK {
  options: SDKOptions;
  report: (data: ErrorEvent) => void;
}

packages/plugin-user-behavior/src/index.ts ​

ts
import type { Plugin } from '@error-sdk/types';

const userActionPlugin: Plugin = {
  name: 'user-action',
  init(sdk) {
    document.addEventListener('click', (e) => {
      sdk.report({
        type: 'custom',
        message: 'User click',
        context: {
          target: (e.target as HTMLElement).tagName,
          timestamp: Date.now()
        }
      });
    });
  }
};

export default userActionPlugin;

技术栈与依赖 ​

类别技术理由
包管理pnpm高效的 Monorepo 管理
构建工具Vite快速构建，支持多格式输出
测试框架Jest + Playwright单元测试和端到端测试
类型检查TypeScript强类型保障，提升代码质量
文档TSDoc自动生成 API 文档
发布Changesets自动化版本管理和发布

Copyright © 2025 梁欢的前后端技术笔记 鲁ICP备2025190626号