Finch SDK

Finch 平台 SDK，支持用户反馈收集和运行时错误追踪。同时适用于浏览器和 Node.js / Bun 服务端环境。

安装

npm install finch-feedback-sdk
# 或
bun add finch-feedback-sdk

也可通过 <script> 标签引入 IIFE 版本，全局变量为 Finch。

快速开始

import { FinchSDK } from 'finch-feedback-sdk';

const sdk = new FinchSDK({
  projectId: 'your-project-id',
  apiUrl: 'https://your-api-url.com',
  userId: 'user-123', // 可选，后续可通过 setUserId 设置
});

错误追踪

SDK 默认自动启用错误追踪，无需额外配置。初始化 SDK 后即可自动捕获全局错误和 console.error。

浏览器端

// 默认即启用错误追踪，无需传 errors 配置
const sdk = new FinchSDK({
  projectId: 'your-project-id',
  apiUrl: 'https://your-api-url.com',
});

// 如需自定义配置：
const sdk = new FinchSDK({
  projectId: 'your-project-id',
  apiUrl: 'https://your-api-url.com',
  errors: {
    captureGlobalErrors: true,   // 自动拦截 window.onerror / unhandledrejection（默认 true）
    captureConsoleErrors: true,   // 拦截 console.error，自动提取 Error 对象堆栈（默认 true）
    maxErrorsPerMinute: 10,      // 客户端限流（默认 10）
    ignorePatterns: [             // 忽略匹配的错误消息（正则字符串）
      'ResizeObserver',
      'Script error',
    ],
  },
});

// 完全禁用错误追踪：
const sdk = new FinchSDK({ projectId: '...', errors: false });

SDK 会自动：

• 监听 window.onerror 捕获未处理的运行时错误
• 监听 unhandledrejection 捕获未处理的 Promise 拒绝
• 拦截 console.error 调用（仍正常输出到控制台），自动从参数中提取 Error 对象的堆栈信息

服务端 (Node.js / Bun)

const sdk = new FinchSDK({
  projectId: 'your-project-id',
  apiUrl: 'https://your-api-url.com',
  // 默认自动启用，可选自定义：
  errors: {
    captureGlobalErrors: true,   // 自动拦截 uncaughtException / unhandledRejection
    captureConsoleErrors: true,   // 拦截 console.error
    maxErrorsPerMinute: 10,
  },
});

服务端模式下，SDK 会自动：

• 监听 process.on('uncaughtException') 捕获未处理异常
• 监听 process.on('unhandledRejection') 捕获未处理的 Promise 拒绝
• 内部定时器使用 unref()，不会阻止进程正常退出

手动上报错误

// 捕获 Error 对象
try {
  riskyOperation();
} catch (error) {
  await sdk.captureError(error, {
    context: 'payment-processing',
    orderId: '12345',
  });
}

// 上报消息（非 Error 对象）
await sdk.captureMessage('用户触发了异常操作', 'WARNING', {
  action: 'deleteAccount',
  userId: 'user-456',
});

框架集成示例

Express / Hono 错误中间件：

app.use((err, req, res, next) => {
  sdk.captureError(err, {
    method: req.method,
    path: req.path,
    query: req.query,
  });
  res.status(500).json({ error: 'Internal Server Error' });
});

Next.js App Router（error.tsx）：

'use client';

export default function ErrorBoundary({ error }: { error: Error }) {
  useEffect(() => {
    sdk.captureError(error);
  }, [error]);

  return <div>Something went wrong</div>;
}

错误去重机制

SDK 和服务端协作实现三层去重，避免数据库爆炸：

1. 客户端限流 — 默认每分钟最多上报 10 条错误
2. 服务端短时去重 — 同一指纹 1 分钟内重复到达只计数不存储
3. 事件采样 — 高频错误按梯度采样存储事件详情（前 10 条全存，10-100 条每 10 条存 1 条，以此类推）

错误计数（eventCount）始终精确，但实际存储的 ErrorEvent 行数被有效控制。

清理

SPA 卸载或服务端关闭时调用 destroy() 清理监听器：

sdk.destroy();

用户反馈

提交反馈

await sdk.submitFeedback({
  type: 'BUG',           // 'AUTO' | 'UI' | 'BUG' | 'FEATURE' | 'OTHER'
  description: '按钮点击无响应',
  screenshots: ['https://...'],  // 可选：截图 URL 数组
});

SDK 会自动附加页面 URL、路由、UserAgent 等上下文信息。在浏览器端，默认还会自动捕获页面 HTML 快照。

页面快照配置

const sdk = new FinchSDK({
  projectId: 'your-project-id',
  snapshot: true,  // 默认 true，服务端自动跳过
  snapshotOptions: {
    sanitizeLinks: true,    // 移除 <a> 的 href（默认 true）
    sanitizeImages: false,  // 替换 <img> 的 src（默认 false）
    sanitizeIframes: true,  // 移除 <iframe>（默认 true）
  },
});

上传截图

const { url } = await sdk.uploadScreenshot(base64Data, 'image/png');

OAuth 登录

用于需要获取用户身份的场景：

const sdk = new FinchSDK({
  projectId: 'your-project-id',
  oauth: {
    clientId: 'your-client-id',
    redirectUri: 'https://your-app.com/callback',
  },
});

// 获取登录 URL
const loginUrl = sdk.getLoginUrl();

// 回调后用授权码换取 token
const tokens = await sdk.exchangeCode(code, clientSecret);

// 获取用户信息
const user = await sdk.getUserInfo(tokens.access_token);
sdk.setUserId(user.id);

API 参考

FinchSDK

| 方法 | 说明 | |------|------| | setUserId(userId) | 设置当前用户 ID | | submitFeedback(data) | 提交用户反馈 | | uploadScreenshot(base64, mimeType) | 上传截图/文件 | | captureError(error, metadata?) | 手动捕获 Error 对象 | | captureMessage(message, severity?, metadata?) | 手动上报消息 | | destroy() | 清理所有监听器和定时器 | | getLoginUrl(state?) | 获取 OAuth 登录 URL | | exchangeCode(code, clientSecret) | 授权码换取 token | | getUserInfo(accessToken) | 获取 OAuth 用户信息 |

FinchSDKConfig

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | projectId | string | 必填 | 项目 ID | | apiUrl | string | https://api.finch.dev | API 地址 | | userId | string | - | 用户 ID | | oauth | OAuthConfig | - | OAuth 配置 | | snapshot | boolean | true | 是否自动捕获页面快照 | | snapshotOptions | SnapshotOptions | - | 快照清理选项 | | errors | ErrorConfig \| false | {} | 错误追踪配置，默认启用；传入 false 禁用 |

ErrorConfig

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | captureGlobalErrors | boolean | true | 自动拦截全局错误 | | captureConsoleErrors | boolean | true | 拦截 console.error，自动提取 Error 堆栈 | | maxErrorsPerMinute | number | 10 | 每分钟最大上报数 | | ignorePatterns | string[] | [] | 忽略的错误消息模式（正则） |

环境兼容性

| 环境 | 自动拦截 | 手动上报 | 反馈 + 快照 | |------|----------|----------|-------------| | 浏览器 | window.onerror / unhandledrejection | captureError / captureMessage | 全部支持 | | Node.js / Bun | uncaughtException / unhandledRejection | captureError / captureMessage | 反馈支持，快照自动跳过 | | IIFE (CDN) | 同浏览器 | Finch.FinchSDK | 全部支持 |