背景

目前CrasheyeCocos已经完成了微信小游戏、抖音小游戏、Windows端的适配

目前支持的平台

平台	类型	说明
Windows	原生 (.dll)	x86_64，通过 CrasheyeNative 全局对象调用
微信小游戏	纯 TypeScript	通过 wx 全局 API 上报
抖音小游戏	纯 TypeScript	通过 tt 全局 API 上报

版本要求

• Cocos Creator >= 3.8.8

工具下载

在SDK下载页面点击下载Cocos Plugin。

CrasheyeCocosPlugin目录结构

解压后你会得到以下目录结构：

crasheye-cocos-plugin/
├── README.md
├── cc_plugin.json                     ← 插件清单（Creator 自动扫描）
├── src/                               ← 跨平台 C++ glue 代码
│   ├── CMakeLists.txt
│   └── crasheye_cocos-glue.cpp
├── windows/                           ← Windows 原生插件
│   ├── crasheye_cocos_glue-config.cmake
│   ├── include/
│   │   └── CrasheyeForWindows.hpp
│   ├── src/
│   │   └── CrasheyeForWindows.cpp
│   └── lib/
│       ├── Crasheye64.dll
│       ├── CrasheyeReport64.exe
│       └── crasheye_windows_sdk.lib
└── assets/                            ← TypeScript 脚本（所有平台共用）
    └── crasheye/
        ├── Crasheye.ts                ← 主入口，静态 API
        ├── CrasheyeComponent.ts       ← 编辑器组件
        ├── CrasheyeDefines.ts         ← 类型定义
        ├── Windows/
        │   └── CrasheyeForWindows.ts
        ├── WeixinMiniGame/
        │   └── CrasheyeForWeixinMiniGame.ts
        └── DouyinMiniGame/
            └── CrasheyeForDouyinMiniGame.ts

目录	用途	目标位置
src/ + windows/ + cc_plugin.json	Windows 原生插件	→ your-project/native/native-plugin/
assets/crasheye/	TypeScript 脚本	→ your-project/assets/crasheye/

快速接入

第一步：复制原生插件（仅 Windows 需要）

如果你只需要小游戏平台，可以跳过此步骤。

将以下目录和文件复制到你的 Cocos 项目的 native/native-plugin/ 下：

cc_plugin.json
src/
windows/

最终目录结构：

your-project/
└── native/
    └── native-plugin/
        ├── cc_plugin.json
        ├── src/
        │   ├── CMakeLists.txt
        │   └── crasheye_cocos-glue.cpp
        └── windows/
            ├── crasheye_cocos_glue-config.cmake
            ├── include/CrasheyeForWindows.hpp
            ├── src/CrasheyeForWindows.cpp
            └── lib/
                ├── Crasheye64.dll
                ├── CrasheyeReport64.exe
                └── crasheye_windows_sdk.lib

Creator 构建 Windows 平台时会自动扫描 cc_plugin.json，编译 glue 代码并将 Crasheye64.dll 复制到输出目录。

第二步：复制 TypeScript 脚本

将 assets/crasheye/ 整个目录复制到你项目的 assets/ 下：

your-project/
└── assets/
    └── crasheye/
        ├── Crasheye.ts               ← 主入口，静态 API
        ├── CrasheyeComponent.ts      ← 编辑器组件（可视化配置 AppKey）
        ├── CrasheyeDefines.ts        ← 类型定义
        ├── Windows/
        │   └── CrasheyeForWindows.ts
        ├── WeixinMiniGame/
        │   └── CrasheyeForWeixinMiniGame.ts
        └── DouyinMiniGame/
            └── CrasheyeForDouyinMiniGame.ts

第三步：初始化

方式一：代码初始化（推荐）

import { Crasheye } from './crasheye/Crasheye';

// 在游戏启动时调用
Crasheye.init('your-app-key', 'your-channel-id');

SDK 会根据 sys.platform 自动选择对应平台的适配器，无需手动判断。

方式二：挂载组件

1. 在场景中新建空节点，命名为 Crasheye

2. 在属性检查器中点击 添加组件 → Crasheye / Crasheye

3. 填写对应平台的 AppKey 和 Channel ID

   ---

各平台配置 AppKey

微信小游戏

在项目构建为微信小游戏后，需在微信公众平台配置 request 合法域名：

域名	用途
https://zyxm.testplus.cn (opens new window)	国内上报（setURL('internal_cn')）
https://api-crasheye.testplus.us/v2 (opens new window)	海外上报（setURL('internal_oversea')）
https://crasheyerp.testplus.cn (opens new window)	外部上报（setURL('external')）

配置路径：微信公众平台 → 开发管理 → 开发设置 → 服务器域名 → request 合法域名

抖音小游戏

在抖音开放平台配置 request 合法域名，同上。

Windows

确保构建输出目录中包含 Crasheye64.dll 和 CrasheyeReport64.exe（CMake 配置会自动复制，参考 crasheye_cocos_glue-config.cmake）。

---

API 参考

所有 API 均为 Crasheye 类的静态方法，调用未实现的 API 不会报错（静默 no-op）。

所有平台通用

这些 API 在 Windows、微信小游戏、抖音小游戏上均可正常使用：

// 初始化
Crasheye.init(appKey: string, channelId?: string): void

// 版本
Crasheye.setAppVersion('1.0.0'): void

// 上报域名（支持别名 'internal_cn' | 'internal_oversea' | 'external' ）
Crasheye.setURL(url: string): void

// 渠道号
Crasheye.setChannelID('release'): void

// 用户标识
Crasheye.setUserIdentifier('player_001'): void

// 自定义数据（微信/抖音 本地存储后随上报附带；Windows 通过 native SetConfig 写入）
Crasheye.addExtraData('key', 'value'): void
Crasheye.addExtraDataUTF8('key', 'value'): void

// 面包屑打点（微信/抖音 本地存储后随上报附带；Windows 使用前必须先调用 setBreadCrumbType）
Crasheye.leaveBreadcrumb('entered_main_scene'): void

// 主动上报脚本异常（微信/抖音 通过 HTTP POST 上报；Windows 通过 native 上报）
Crasheye.sendScriptException('error title'): void
Crasheye.sendScriptException('error title', 'stack trace', 'javascript'): void

微信小游戏 / 抖音小游戏额外支持

// 移除指定 Key 的自定义数据
Crasheye.removeExtraData('key'): void

// 清空全部自定义数据
Crasheye.cleanExtraData(): void

Windows 原生额外支持

这些 API 仅在 Windows 平台生效，通过 Crasheye64.dll 写入崩溃报告：

// 面包屑编码格式（0=ANSI, 1=UTF8，必须在 leaveBreadcrumb 之前调用）
Crasheye.setBreadCrumbType(1): void

// 崩溃回调
Crasheye.setCrashCallback((success: boolean, filePath: string) => {
    console.log('crash captured:', success, filePath);
}): boolean

// 上传控制
Crasheye.setForceUpload(true): void
Crasheye.setBackgroundUpload(true): boolean
Crasheye.setIsBetaVersion(true): void

// 日志追踪与收集
Crasheye.pushLogTrace('message'): boolean
Crasheye.addCustomLog('C:/logs/game.log'): void
Crasheye.addCustomLogDirectory('C:/logs/'): void

// 环境信息（写入崩溃报告附加字段）
Crasheye.setApplicationRegion('CN'): void
Crasheye.setGraphicsAPI('DirectX11'): void
Crasheye.setGraphicsQuality('High'): void
Crasheye.setLangID('zh_CN'): void
Crasheye.setServerInfo('ServerGroupA'): void

---

完整使用示例

import { _decorator, Component } from 'cc';
import { Crasheye } from './crasheye/Crasheye';

const { ccclass } = _decorator;

@ccclass('GameMain')
export class GameMain extends Component {

    onLoad(): void {
         // 基础配置
        Crasheye.setAppVersion('1.2.0');
        Crasheye.setURL('internal_cn');

        // 初始化
        Crasheye.init('your-app-key', 'release');

        // 用户标识
        Crasheye.setUserIdentifier('player_001');

        // 自定义业务数据
        Crasheye.addExtraData('server', 'asia-1');
        Crasheye.addExtraData('guild', 'shadow_blade');

        // 关键流程打点
        Crasheye.leaveBreadcrumb('player_entered_main_city');

        // Windows 原生崩溃回调
        Crasheye.setCrashCallback((success, file) => {
            if (success) {
                console.log('崩溃报告已保存:', file);
            }
        });
    }

    handleError(error: Error): void {
        Crasheye.sendScriptException(error.message, error.stack, 'TypeScript');
    }
}