XConsole SDK

一个功能强大的网页远程调试 SDK，支持 console、network 和 error 的 hook，同时保持 DevTools 的源代码定位能力。

核心特性

✨ 智能 Console Hook

• 拦截 console.log/info/warn/error/debug
• 保留原始调用栈，DevTools 仍能定位源代码
• 使用 Proxy + apply 技术保持调用链完整
• 递归保护防止无限循环

🌐 Network Hook

• 自动拦截 Fetch API 请求
• 自动拦截 XMLHttpRequest 请求
• 记录请求头、响应头、请求体、响应体
• 自动计算请求耗时

⚠️ Error Hook

• 捕获全局错误 (window.onerror)
• 捕获未处理的 Promise 拒绝 (unhandledrejection)
• 保留完整的错误堆栈信息

📊 数据管理

• 灵活的日志存储限制
• 支持实时数据回调
• 支持导出到远程服务器

安装

NPM 方式（推荐）

npm install xconsole-sdk
# 或
yarn add xconsole-sdk
# 或
pnpm add xconsole-sdk

浏览器直接引入

<!-- 使用 IIFE bundle（无需打包工具） -->
<script src="dist-browser/bundle.js"></script>
<script>
  const xconsole = new XConsole();
  xconsole.install();
</script>

快速开始

ES Module（推荐）

import { XConsole } from 'xconsole-sdk';

// 创建实例和配置
const xconsole = new XConsole({
  enabled: true,
  maxConsoles: 1000,
  maxNetworks: 500,
  maxErrors: 500,
  onMessage: (data) => {
    console.log('SDK Event:', data.type, data.data);
  }
});

// 安装 hook
xconsole.install();

// 现在所有 console/fetch/error 都被自动拦截
console.log('Hello World');
fetch('/api/data');

// 获取所有日志
const logs = xconsole.getLogs();
console.log('Consoles:', logs.consoles);
console.log('Networks:', Array.from(logs.networks.values()));
console.log('Errors:', logs.errors);

// 上报到服务器
await xconsole.reportToServer();

// 卸载 hook（如需）
// xconsole.uninstall();

TypeScript 方式

import { XConsole, XConsoleConfig } from 'xconsole-sdk';

const config: XConsoleConfig = {
  enabled: true,
  maxConsoles: 1000,
  serverUrl: 'https://api.example.com/logs'
};

const xconsole = new XConsole(config);
xconsole.install();

CommonJS 方式

const { XConsole } = require('xconsole-sdk');

const xconsole = new XConsole();
xconsole.install();

浏览器直接引用

<script src="dist-browser/bundle.js"></script>

<script>
  // 创建实例
  const xconsole = new XConsole({
    enabled: true,
    maxConsoles: 1000,
    onMessage: function(data) {
      // 接收实时事件
      updateUI(data);
    }
  });

  // 安装 hook
  xconsole.install();

  // 你的业务代码...
  console.log('App Started');
</script>

API 文档

构造函数

new XConsole(config?: XConsoleConfig)

参数：

• enabled - 是否启用（默认 true）
• maxConsoles - Console 日志最大数量（默认 1000）
• maxNetworks - Network 请求最大数量（默认 500）
• maxErrors - Error 日志最大数量（默认 500）
• serverUrl - 远程上报服务器地址（可选）
• onMessage - 实时消息回调函数（可选）

方法

install(): void

安装所有 hook。

xconsole.install();

uninstall(): void

卸载所有 hook。

xconsole.uninstall();

getLogs(): Logs

获取所有日志。

const logs = xconsole.getLogs();
// {
//   consoles: ConsoleMessage[],
//   networks: Map<string, NetworkRequest>,
//   errors: ErrorMessage[]
// }

getConsoleLogs(): ConsoleMessage[]

获取 console 日志。

getNetworkRequests(): NetworkRequest[]

获取 network 请求。

getErrors(): ErrorMessage[]

获取 error 日志。

clearLogs(): void

清空所有日志。

reportToServer(): Promise<void>

上报日志到远程服务器（需要配置 serverUrl）。

await xconsole.reportToServer();

getStatus(): XConsoleStatus

获取 SDK 状态。

const status = xconsole.getStatus();
// {
//   installed: boolean,
//   config: XConsoleConfig,
//   stats: { consoles, networks, errors }
// }

核心原理

关键技术：Proxy + 保留原始调用栈

// 使用 Proxy 的 apply 陷阱拦截函数调用
(console as any)[level] = new Proxy(originalMethod, {
  apply: (target, thisArg, args) => {
    // 防止递归
    if (this.isProcessing) {
      return target.apply(console, args);
    }
    
    try {
      this.isProcessing = true;
      
      // 1. 记录数据（不影响调用栈）
      const message = this.parseMessage(args);
      this.addMessage(message);
      this.onMessage?.(message);
      
      // 2. 调用原始方法 - 关键：直接 apply
      // 这保证了调用栈完整，DevTools 仍能定位源代码行
      return target.apply(console, args);
    } finally {
      this.isProcessing = false;
    }
  }
});

为什么这样设计？

1. 保持调用栈完整：使用 Proxy 和 apply，不添加额外的栈帧
2. DevTools 定位能力：点击 DevTools 中的日志仍能准确定位源代码行号
3. 递归保护：isProcessing 标志防止 onMessage 中的 console 调用引起无限递归
4. 零侵入：对业务代码完全透明，无任何副作用

构建方案

项目使用 Vite 库模式打包，生成多种格式：

dist/
├── index.js (9.0 KB) - ES Module
├── index.umd.js (1.6 KB) - UMD（CommonJS 兼容）
├── index.d.ts - TypeScript 类型定义
└── *.map - 源映射

dist-browser/
└── bundle.js (9.0 KB) - IIFE（直接浏览器使用）

构建命令

# 构建库（ESM + UMD + 类型定义）
npm run build

# 构建浏览器包
npm run build:example

# 监视开发模式
npm run dev

# 运行单元测试
npm run test

# 启动演示服务器
npm run example

开发

项目结构

src/
├── index.ts        - 主入口
├── browser.ts      - 浏览器入口
├── consoleHook.ts  - Console 拦截实现
├── networkHook.ts  - Network 拦截实现
├── errorHook.ts    - Error 拦截实现
├── types.ts        - TypeScript 类型定义
└── utils.ts        - 工具函数

本地开发

# 安装依赖
npm install

# 运行测试
npm run test

# 启动演示服务
npm run example
# 访问 http://localhost:8080

性能考虑

• 内存使用：默认保存最近 1000 条 console、500 条 network、500 条 error
• CPU 影响：最小化开销，使用 WeakMap 自动垃圾回收
• 网络上报：batch 处理，支持自定义上报间隔

浏览器兼容性

• 现代浏览器（推荐）：Chrome 60+, Firefox 55+, Safari 12+, Edge 79+
• 使用 UMD：支持 CommonJS 和 AMD
• 使用 IIFE：支持 ES5+ 的所有浏览器

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request！