跳到主要内容

Electron CrashSight 接入指南

本文档将指导您如何在 Electron 项目中接入 crashsight-electron 插件，实现崩溃上报功能。

前置要求​

  • Node.js 环境（推荐 16.x 或更高版本）
  • Electron 项目已创建
  • Windows 开发环境（需要 Visual Studio 或 Windows Build Tools 用于编译原生模块）

一、安装插件​

1.1 复制插件目录​

将 crashsight-electron 目录复制到您的 Electron 项目根目录下。

your-electron-project/
├── main.js
├── package.json
├── crashsight-electron/    ← 复制到这里
│   ├── libs/
│   │   └── CrashSight64.dll
│   ├── src/
│   ├── package.json
│   └── ...
└── ...

1.2 安装依赖​

在项目根目录的 package.json 中添加依赖：

{
  "dependencies": {
    "crashsight-electron": "file:./crashsight-electron"
  }
}

然后运行：

npm install

注意：安装过程中会自动编译原生模块。如果编译失败，请确保已安装：

  • Windows: Visual Studio 2019/2022 或 Windows Build Tools
  • 编译工具会自动安装，首次安装可能需要较长时间

版本兼容性说明：

  • 本插件使用 N-API（Node-API），具有良好的跨版本兼容性
  • 已通过以下 Electron 版本的兼容性测试（100% 通过率）：
    • ✅ Electron 16.2.0 (Node.js 16.14.2)
    • ✅ Electron 18.3.0 (Node.js 16.14.2)
    • ✅ Electron 20.3.0 (Node.js 16.15.0)
    • ✅ Electron 22.3.0 (Node.js 18.15.0)
    • ✅ Electron 27.3.0 (Node.js 18.17.1)
  • 理论上支持 Electron 16+ 和 Node.js 16+
  • 如果遇到模块加载错误，请运行 npx electron-rebuild 重新编译

二、配置打包选项​

2.1 配置 electron-builder​

在项目根目录的 package.json 中添加或修改 build 配置：

{
  "build": {
    "files": [
      "main.js",
      "index.html",
      "crashsight-electron/**/*",
      "!crashsight-electron/**/*.{md,ts,map}",
      "node_modules/**/*",
      "!node_modules/**/*.{md,ts,map}",
      "!**/*.{md,ts,map}"
    ],
    "asarUnpack": [
      "crashsight-electron/libs/**/*",
      "crashsight-electron/build/**/*"
    ]
  }
}

重要说明：

  • asarUnpack 配置是必需的，用于将 DLL 和原生模块从 asar 包中解压出来
  • 这些文件必须解压才能被系统加载

三、初始化 CrashSight​

3.1 在主进程中引入模块​

在您的主进程文件（通常是 main.js）中引入 CrashSight：

const { app, BrowserWindow } = require('electron');
const { CrashSightAgent, CrashSightLogLevel } = require('crashsight-electron');
const path = require('path');

3.2 初始化配置​

在 app.whenReady() 中初始化 CrashSight。必须在创建窗口之前初始化：

let crashSight = null;

function initCrashSight() {
    try {
        crashSight = new CrashSightAgent();
        
        // 1. 配置调试模式（可选，开发环境建议开启）
        crashSight.configDebugMode(true);  // 生产环境建议设为 false
        
        // 2. 配置服务器 URL（必需）
        crashSight.configCrashServerUrl('pc.crashsight.qq.com');
        
        // 3. 配置日志级别（可选）
        crashSight.configCrashReporter(CrashSightLogLevel.CSLogLevelInfo);
        
        // 4. 设置应用版本（推荐）
        crashSight.setAppVersion(app.getVersion());
        
        // 5. 设置用户 ID（可选，用于标识用户）
        crashSight.setUserId('your-user-id');
        
        // 6. 设置日志路径（可选，用于存储 CrashSight 日志）
        crashSight.setLogPath(path.join(app.getPath('userData'), 'crashsight-logs'));
        
        // 7. 启用 VEH（可选，Windows 平台）
        crashSight.setVehEnable(true);
        
        // 8. 初始化（会自动注册异常处理器）
        crashSight.initWithAppId('your-app-id');
        
    } catch (error) {
        console.error('Failed to initialize CrashSight:', error);
        // 即使 CrashSight 初始化失败，应用也应该继续运行
    }
}

app.whenReady().then(() => {
    // 先初始化 CrashSight
    initCrashSight();
    
    // 然后创建窗口
    createWindow();
});

3.3 配置参数说明​

方法说明是否必需调用时机
configDebugMode(enable)开启/关闭调试模式可选初始化前
configCrashServerUrl(url)设置崩溃上报服务器地址必需初始化前
configCrashReporter(level)设置日志级别可选初始化前
setAppVersion(version)设置应用版本号推荐初始化前
setUserId(userId)设置用户 ID可选初始化前/后
setLogPath(path)设置日志存储路径可选初始化前
setVehEnable(enable)启用 VEH（Windows）可选初始化前
initWithAppId(appId)使用 AppId 初始化必需最后调用

重要提示：

  • initWithAppId() 会自动注册主进程的异常处理器，捕获未捕获的异常和未处理的 Promise 拒绝
  • 所有配置方法（除了 setUserId）必须在 initWithAppId() 之前调用
  • 如果初始化失败，应用仍会继续运行，但崩溃上报功能将不可用

四、获取 AppId​

  1. 登录 CrashSight 控制台
  2. 创建应用或选择已有应用
  3. 在应用设置中获取 AppId
  4. 将 AppId 替换到代码中的 'your-app-id'

五、测试验证​

5.1 开发环境测试​

运行应用：

npm start

5.2 测试异常捕获​

CrashSight 会自动捕获以下异常：

  1. 主进程未捕获异常：在主进程中直接抛出异常
  2. 主进程未处理的 Promise 拒绝：在主进程中触发未处理的 Promise 拒绝

5.3 打包测试​

打包应用：

npm run build:win

打包后的应用位于 dist/win-unpacked/ 目录，运行打包后的应用验证功能是否正常。

六、高级配置（可选）​

6.1 自定义 DLL 路径​

如果您的 DLL 文件不在默认位置，可以指定路径：

const crashSight = new CrashSightAgent({
    libPath: 'C:\\path\\to\\CrashSight64.dll'
});

6.2 设置工作空间​

crashSight.setWorkSpaceW('D:\\workspace');

6.3 手动上报异常​

crashSight.reportException(
    4,                          // 异常类型
    'ErrorName',                // 异常名称
    'Error message',            // 异常消息
    'Stack trace...',           // 堆栈信息
    JSON.stringify({extra: 'data'}),  // 额外信息（JSON 字符串）
    false,                      // 是否异步上报（false 表示同步）
    ''                          // 附件路径（可选）
);

6.4 设置用户自定义值​

// 设置整数类型
crashSight.setUserValue('level', 10);

// 设置字符串类型
crashSight.setUserValue('username', 'user123');

// 设置字符串数组类型
crashSight.setUserValue('tags', ['tag1', 'tag2', 'tag3']);

七、完整 API 参考​

7.1 初始化接口​

initWithAppId(appId)​

初始化 CrashSight SDK。

参数：

  • appId (string, 必需): 已注册项目的 APPID

说明：

  • 在尽可能早的位置进行初始化以开启崩溃捕获和上报功能
  • 会自动注册主进程的异常处理器，捕获未捕获的异常和未处理的 Promise 拒绝
  • 必须在所有配置方法之后调用

示例：

crashSight.initWithAppId('your-app-id');

7.2 配置接口​

configDebugMode(enable)​

设置调试模式。

参数：

  • enable (boolean): 是否启用调试模式

说明：

  • 默认关闭
  • 需要在 initWithAppId() 之前调用
  • 开启后会打印更多便于问题定位的日志

示例：

crashSight.configDebugMode(true);  // 开发环境
crashSight.configDebugMode(false); // 生产环境

configCrashServerUrl(url)​

设置崩溃上报服务器地址。

参数：

  • url (string, 必需): 要上报的域名，例如 'pc.crashsight.qq.com'

说明：

  • 需要在 initWithAppId() 之前调用

示例：

crashSight.configCrashServerUrl('pc.crashsight.qq.com');

configCrashReporter(level)​

设置自定义日志上报级别。

参数：

  • level (number): 日志级别
    • 0: Off（关闭）
    • 1: Error（错误）
    • 2: Warn（警告）
    • 3: Info（信息，默认）
    • 4: Debug（调试）

说明：

  • 需要在 initWithAppId() 之前调用
  • 可以使用 CrashSightLogLevel 枚举值

示例：

crashSight.configCrashReporter(CrashSightLogLevel.CSLogLevelInfo);

setAppVersion(version)​

设置应用版本号。

参数：

  • version (string): 版本号字符串

说明：

  • 需要在 initWithAppId() 之前调用

示例：

crashSight.setAppVersion('1.0.0');

setUserId(userId)​

设置用户 ID。

参数：

  • userId (string): 用户标识符

说明：

  • 用户 ID 默认为 "unknown"
  • 可以在初始化前或初始化后调用

示例：

crashSight.setUserId('user123');

setDeviceId(deviceId)​

设置设备 ID。

参数：

  • deviceId (string): 设备唯一标识

说明：

  • 默认采用 UUID 作为设备 ID
  • 需要在 initWithAppId() 之前调用

示例：

crashSight.setDeviceId('device-uuid-123');

setLogPath(path)​

设置崩溃后上传的日志路径。

参数：

  • path (string): 日志文件的绝对路径

说明：

  • 需要可读权限
  • 需要在 initWithAppId() 之前调用
  • 不支持 GBK 字符路径（如需支持，使用 setLogPathW）

示例：

crashSight.setLogPath('C:\\logs\\crashsight');

setLogPathW(path)​

设置崩溃后上传的日志路径（宽字符版本，支持 GBK 字符）。

参数：

  • path (string): 日志文件的绝对路径（支持中文等 GBK 字符）

说明：

  • 需要可读权限
  • 需要在 initWithAppId() 之前调用
  • 仅 Windows 平台有效

示例：

crashSight.setLogPathW('D:\\中文路径\\logs');

setEnvironmentName(serverEnv)​

设置发行渠道。

参数：

  • serverEnv (string): 发行渠道名称

说明：

  • 每一个联网或者上报都可以携带该字段，可实现针对不同的发行渠道统计数据

示例：

crashSight.setEnvironmentName('production');

7.3 异常上报接口​

reportException(type, name, reason, stackTrace, extras, isAsync, errorAttachPath?)​

主动上报错误。

参数：

  • type (number, 必需): 异常类型
    • 0-3: 内部保留类型，传入无效
    • 4: C# 异常
    • 5: JavaScript 异常
    • 6: Lua 异常
  • name (string, 必需): 异常名称，不能为 null
  • reason (string, 必需): 异常原因，不能为 null
  • stackTrace (string, 必需): 堆栈信息，不能为 null
  • extras (string): 额外信息（JSON 字符串）
  • isAsync (boolean): 是否异步上报（仅 Win/Xbox 有效）
    • true: 异步上报（默认）
    • false: 同步上报（会阻塞直到上报完成）
  • errorAttachPath (string, 可选): 附件的绝对路径（不支持 GBK 字符，Win/Xbox 有效）

说明：

  • 可以在捕获到错误或者需要上报的时候手动调用
  • 支持多线程调用
  • 如果 isAsync 为 false，会同步等待上报完成，适用于应用退出前的上报

示例：

crashSight.reportException(
    5,  // JavaScript 异常
    'TypeError',
    'Cannot read property of undefined',
    'at Object.<anonymous> (file.js:10:5)\n...',
    JSON.stringify({ userId: '123', level: 10 }),
    false,  // 同步上报
    ''  // 无附件
);

reportExceptionW(type, name, reason, stackTrace, extras, isAsync, errorAttachPath?)​

主动上报错误（宽字符版本，支持 GBK 字符路径）。

参数：

  • type (number, 必需): 异常类型（同 reportException）
  • name (string, 必需): 异常名称
  • reason (string, 必需): 异常原因
  • stackTrace (string, 必需): 堆栈信息
  • extras (string): 额外信息（JSON 字符串）
  • isAsync (boolean): 是否异步上报
  • errorAttachPath (string, 可选): 日志附件路径（宽字符，支持 GBK 字符，仅 Windows 有效）

说明：

  • 功能与 reportException 相同，但支持带 GBK 字符的附件路径
  • 仅 Windows 平台有效

示例：

crashSight.reportExceptionW(
    5,
    'TypeError',
    'Error message',
    'Stack trace...',
    '',
    false,
    'D:\\中文路径\\attachment.log'
);

7.4 用户自定义数据接口​

addSceneData(key, value)​

添加自定义数据（Key-Value）。

参数：

  • key (string): 键名
  • value (string): 值（字符串类型）

说明：

  • 设置用户自定义的 Key-Value 数据，将在发送 Crash 时随异常信息一起上报
  • 页面查看：崩溃详情页 -> 附件下载 -> valueMapOthers.txt

示例：

crashSight.addSceneData('level', '10');
crashSight.addSceneData('scene', 'battle');

setUserValue(key, value)​

设置用户自定义值（支持多种类型）。

参数：

  • key (string): 键名
  • value (number | string | string[]): 值
    • number: 整数类型
    • string: 字符串类型
    • string[]: 字符串数组类型

说明：

  • 内部调用 addSceneData，自动添加类型前缀
  • 整数类型使用 I# 前缀
  • 字符串类型使用 K# 前缀
  • 字符串数组类型使用 S# 前缀

示例：

// 整数类型
crashSight.setUserValue('level', 10);

// 字符串类型
crashSight.setUserValue('username', 'user123');

// 字符串数组类型
crashSight.setUserValue('tags', ['tag1', 'tag2', 'tag3']);

7.5 Windows 平台专用接口​

setVehEnable(enable)​

设置 VEH（向量化异常处理）捕获开关。

参数：

  • enable (boolean): 是否启用 VEH

说明：

  • 仅 Win/Xbox 平台有效
  • 需要在 initWithAppId() 之前调用
  • VEH 可以捕获更多类型的崩溃

示例：

crashSight.setVehEnable(true);

reportCrash()​

主动上报崩溃信息。

说明：

  • 仅 Win/Xbox 平台有效
  • 手动触发崩溃上报

示例：

crashSight.reportCrash();

reportDump(dumpPath, isAsync)​

主动上报 dump 文件。

参数：

  • dumpPath (string): Dump 文件目录
  • isAsync (boolean): 是否异步上报

说明：

  • 仅 Win/Xbox 平台有效

示例：

crashSight.reportDump('C:\\dumps', true);

setCrashCallback(callback)​

设置崩溃回调。

参数：

  • callback (Function): 崩溃回调函数
    • 函数签名：(type: number, guid: string) => void
    • type: 崩溃类型
    • guid: 问题 GUID

说明：

  • 仅 Win/Xbox 平台有效
  • 回调在崩溃时调用，返回值随崩溃信息一起上报

示例：

crashSight.setCrashCallback((type, guid) => {
    console.log(`Crash occurred: type=${type}, guid=${guid}`);
});

setExtraHandler(enable)​

设置额外异常捕获的开关。

参数：

  • enable (boolean): 是否启用额外异常处理

说明：

  • 仅 Win/Xbox 平台有效

示例：

crashSight.setExtraHandler(true);

uploadGivenPathDump(dumpDir, isExtraCheck)​

上传指定路径的 dump 文件。

参数：

  • dumpDir (string): Dump 文件目录
  • isExtraCheck (boolean): 额外校验检查，默认填 false 即可

说明：

  • 仅 Win/Xbox 平台有效

示例：

crashSight.uploadGivenPathDump('C:\\dumps', false);

unrealCriticalErrorEnable(enable)​

开启/关闭 UE Critical Error 上报。

参数：

  • enable (boolean): 是否启用

说明：

  • 仅 Win/Xbox 平台有效
  • 用于 Unreal Engine 项目

示例：

crashSight.unrealCriticalErrorEnable(true);

onlyUploadFirstCrash(enable)​

仅上报首条崩溃的开关。

参数：

  • enable (boolean): 是否仅上报首条崩溃

说明：

  • 仅 Win/Xbox 平台有效
  • 开启 VEH 捕获后才生效

示例：

crashSight.onlyUploadFirstCrash(true);

setDumpType(dumpType)​

设置 dump 类型。

参数：

  • dumpType (number): Dump 类型，详见 Windows 官方定义

说明：

  • 仅 Win/Xbox 平台有效
  • 使用前请咨询 CrashSight 开发人员

示例：

crashSight.setDumpType(1);

addValidExpCode(expCode)​

添加可用的异常类型。

参数：

  • expCode (number): 异常代码，详见 Windows 官方定义

说明：

  • 仅 Win/Xbox 平台有效
  • 使用前请咨询 CrashSight 开发人员

示例：

crashSight.addValidExpCode(0xC0000005);

uploadCrashWithGuid(guid)​

根据问题 GUID 上报。

参数：

  • guid (string): GUID，指向唯一问题的代码，可通过回调获取

说明：

  • 仅 Win/Xbox 平台有效

示例：

crashSight.uploadCrashWithGuid('12345678-1234-1234-1234-123456789abc');

setCrashUploadEnable(enable)​

设置崩溃上报开关。

参数：

  • enable (boolean): 是否启用崩溃上报

说明：

  • 仅 Win/Xbox 平台有效

示例：

crashSight.setCrashUploadEnable(true);

setWorkSpace(workspace)​

设置工作空间。

参数：

  • workspace (string): 工作空间的绝对路径

说明：

  • 仅 Win/Xbox 平台有效
  • 不支持 GBK 字符路径（如需支持，使用 setWorkSpaceW）

示例：

crashSight.setWorkSpace('C:\\workspace');

setWorkSpaceW(workspace)​

设置工作空间（宽字符版本，支持 GBK 字符）。

参数：

  • workspace (string): 工作空间的绝对路径（支持中文等 GBK 字符）

说明：

  • 仅 Win/Xbox 平台有效

示例：

crashSight.setWorkSpaceW('D:\\中文workspace');

setAttachPath(attachPath)​

设置自定义附件路径。

参数：

  • attachPath (string): 附件的绝对路径

说明：

  • 仅 Win/Xbox 平台有效
  • 不支持 GBK 字符路径（如需支持，使用 setAttachPathW）

示例：

crashSight.setAttachPath('C:\\attachments');

setAttachPathW(attachPath)​

设置自定义附件路径（宽字符版本，支持 GBK 字符）。

参数：

  • attachPath (string): 附件的绝对路径（支持中文等 GBK 字符）

说明：

  • 仅 Win/Xbox 平台有效

示例：

crashSight.setAttachPathW('D:\\中文附件路径');

7.6 其他接口​

printLog(level, tag, format, ...args)​

添加自定义日志。

参数：

  • level (number): 日志级别（0-4，对应 Off/Error/Warn/Info/Debug）
  • tag (string): 日志标签
  • format (string): 格式化字符串，支持 {0}, {1} 等占位符
  • ...args: 可变参数，用于替换格式化字符串中的占位符

说明：

  • 自定义日志限制 30KB
  • 自定义日志查看：问题详情 -> 自定义日志（来自接口）

示例：

crashSight.printLog(
    CrashSightLogLevel.CSLogLevelInfo,
    'MyTag',
    'User {0} completed level {1}',
    'user123',
    10
);

testNativeCrash()​

测试 native 崩溃。

说明：

  • 用于测试崩溃捕获功能
  • 警告：调用此方法会导致应用立即崩溃

示例：

crashSight.testNativeCrash();  // 应用会立即崩溃

setEngineInfo(version?, buildConfig?, language?, locale?)​

设置引擎信息（由插件自动调用）。

参数：

  • version (string, 可选): 引擎版本
  • buildConfig (string, 可选): 构建配置
  • language (string, 可选): 语言
  • locale (string, 可选): 区域设置

说明：

  • 通常由插件自动调用，无需手动设置
  • 会自动检测 Electron 和 Node.js 版本信息

getCrashThreadId()​

获取崩溃线程 ID。

返回值：

  • number: 崩溃线程的 ID，失败返回 -1

说明：

  • 仅 Win/Xbox 平台有效

示例：

const threadId = crashSight.getCrashThreadId();

getSessionId()​

获取 SDK 生成的 session ID。

返回值：

  • string: Session ID 字符串

示例：

const sessionId = crashSight.getSessionId();

setCrashObserver(crashObserver)​

设置崩溃观察者。

参数：

  • crashObserver (object): 崩溃观察者对象（需要实现特定接口）

说明：

  • 此接口在当前 Electron 版本中可能不完全支持
  • 建议使用 setCrashCallback 替代

reportStuck(threadId, maxChecks, checkInterval, name, message, extraInfo, dumpNativeType, attachPath)​

上报卡顿。

参数：

  • threadId (number): 线程 ID
  • maxChecks (number): 最大检查次数
  • checkInterval (number): 检查间隔（毫秒）
  • name (string): 异常名称
  • message (string): 异常消息
  • extraInfo (string): 额外信息
  • dumpNativeType (number): Dump 类型
  • attachPath (string): 附件路径

说明：

  • 用于上报线程卡顿问题

示例：

crashSight.reportStuck(
    12345,  // threadId
    10,     // maxChecks
    1000,   // checkInterval (ms)
    'ThreadStuck',
    'Main thread stuck for 10 seconds',
    JSON.stringify({ scene: 'loading' }),
    0,      // dumpNativeType
    ''      // attachPath
);

7.7 日志级别枚举​

const CrashSightLogLevel = {
    CSLogLevelSilent: 0,  // 关闭
    CSLogLevelError: 1,   // 错误
    CSLogLevelWarn: 2,    // 警告
    CSLogLevelInfo: 3,    // 信息（默认）
    CSLogLevelDebug: 4,   // 调试
    CSLogLevelVerbose: 5  // 详细
};

八、常见问题​

Q1: 安装时编译失败怎么办？​

A: 确保已安装：

  • Windows: Visual Studio 2019/2022 或 Windows Build Tools
  • 运行 npm install --global windows-build-tools（如果使用 npm）

Q2: 打包后无法加载 DLL？​

A: 检查以下几点：

  1. 确保 asarUnpack 配置正确
  2. 检查打包后的 app.asar.unpacked 目录中是否有 DLL 文件
  3. 确认 DLL 路径是否正确

Q3: 异常没有被捕获？​

A:

  • 确保 initWithAppId() 已成功调用
  • 异常必须是在主进程中抛出的
  • 渲染进程的异常不会被自动捕获（仅捕获主进程异常）

Q4: 如何查看上报是否成功？​

A:

  • 登录 CrashSight 控制台查看上报记录
  • 检查日志文件（如果设置了日志路径）

Q5: 支持哪些 Electron 版本？​

A:

  • 已测试版本（全部通过）：

    Electron 版本Node.js 版本状态
    16.2.016.14.2✅ 通过
    18.3.016.14.2✅ 通过
    20.3.016.15.0✅ 通过
    22.3.018.15.0✅ 通过
    27.3.018.17.1✅ 通过

  • 兼容性说明：

    • 本插件使用 N-API，理论上支持 Electron 16+ 和 Node.js 16+
    • 所有测试版本均通过安装、编译和模块加载测试
    • 测试通过率：100%（5/5）

  • 如果使用其他版本：

    1. 运行 npx electron-rebuild 重新编译原生模块
    2. 测试基本功能是否正常
    3. 如遇问题，请检查 Electron 版本是否过旧（建议 16+）