故障排查¶

初始化后无数据¶

依次检查：

必须使用 Android 或 iOS 原生构建，浏览器预览和 Web 构建不会上报。
确认已执行 npx @cloudcare/cocos-sdk install --project .，重新打开 Cocos Creator 并启用 guance-cocos-sdk 扩展。
升级或重新安装 npm 包后，必须重新生成原生工程。
确认 datakitUrl，或 datawayUrl 与 clientToken 配置正确。
Android 必须提供 androidAppId，iOS 必须提供 iosAppId。
初始化阶段设置 debug: true，检查 Cocos 和原生日志。
确认 sampleRate 不为 0。
如使用本地环境部署，继续排查 DataKit 无数据问题。

安装器提示找不到 Cocos 项目¶

如果出现：

No Cocos project found ... (missing assets directory)

--project 必须指向包含 assets 目录的 Cocos 项目根目录：

npx @cloudcare/cocos-sdk install --project /absolute/path/to/cocos-project

使用了错误的 Creator 入口¶

Creator 2 和 Creator 3 使用同一个 @cloudcare/cocos-sdk npm 包，但导入入口不同：

Creator 2：@cloudcare/cocos-sdk/creator2
Creator 3：@cloudcare/cocos-sdk/creator3

修改导入入口后，重新运行安装器并生成原生工程。如果安装器无法识别 Creator 版本，显式传入 --creator 2 或 --creator 3。

Android Bridge 或依赖错误¶

出现 ClassNotFoundException、FTCocosBridge 找不到或 Guance SDK 类缺失时：

确认生成工程包含 guance-cocos-sdk-native/android。
检查应用模块 build.gradle 中是否存在 GUANCE_COCOS_SDK_BEGIN 标记块。
确认 Gradle 可以访问 https://mvnrepo.guance.com/repository/maven-releases。
确认 AndroidX 已启用。
确认 Compile SDK 与 Build Tools 不低于 34，Min SDK 不低于 21。
重新运行安装器并重新生成工程，不要只复用旧的 Native 工程。

iOS Bridge 或 CocoaPods 错误¶

确认生成工程包含 guance-cocos-sdk-native/ios。
确认 Podfile 中存在 pod 'FTCocosBridge'。
在 Podfile 所在目录重新执行 pod install。
使用 .xcworkspace，不要使用 .xcodeproj。
清理 Xcode Build Folder 后重新构建。

Creator 2 工程的 iOS 最低版本会被提升到 12.0；Xcode 15 兼容链接参数由构建扩展自动写入生成配置。

iOS Session Replay API 缺失¶

出现：

FTMobileSDK lacks external Session Replay API

表示当前 GuanceSDK 不包含 Cocos External Replay API：

升级到支持 Cocos 的 iOS SDK 版本；
重新执行 pod install；
清理并重新构建 .xcworkspace。

升级前可以移除 replay 配置，RUM、Log 和 Trace 仍可使用。

有 RUM，但没有 View¶

开启 autoTrack.scenes: true；或
在业务场景进入时调用 guanceSdk.rum.startView()，离开时调用 stopView()。

初始化时间晚于首个场景启动时，可能错过场景事件。应在首个采集场景前初始化。

自动 Action 或 Error 不生效¶

Action：

确认 autoTrack.actions: true；
确认交互最终触发全局 TOUCH_END；
自定义输入系统或吞掉全局事件的组件需要手动调用 Action API。

Error：

确认 autoTrack.errors: true；
当前运行时必须提供全局 addEventListener；
已被业务 try/catch 捕获的异常需要手动调用 addError()。

Log 无数据或没有 RUM 关联¶

初始化 logger 并设置 enableCustomLog: true。
检查 sampleRate 和 logLevelFilters。
Console 采集还需要 autoTrack.console: true。
RUM 关联需要 enableLinkRumData: true、有效 RUM Session 和当前 View。
早于首个 View 产生的日志可能没有 View 关联。

Trace Header 为空¶

确认已初始化 trace。
URL 不能为空且必须是 Native SDK 可处理的有效 URL。
检查 Trace 采样率。
不支持平台会返回空对象。
自动注入只覆盖运行时提供的 fetch 和 XMLHttpRequest。

网络数据重复¶

检查是否同时开启：

autoTrack.network 与 enableNativeUserResource；
autoTrack.network 与 enableNativeAutoTrace；
自动网络采集与业务手动 Resource/Trace。

对同一请求栈保留一种采集路径，再比较 RUM Resource 数量与请求头。

Session Replay 没有画面¶

确认已初始化 RUM 且当前存在有效 View。
确认场景中存在 Camera，或调用 setReplayCamera()。
确认 Replay 与 RUM 的采样率不为 0。
静止画面会被判定为重复帧并跳过。
检查控制台是否出现捕获停止错误。
iOS 检查 External Replay API，Android 检查 Session Replay 原生依赖。

初始化参数抛出异常¶

错误	原因
`Configure datakitUrl or datawayUrl with clientToken`	未配置有效上报地址
`... must be between 0 and 1`	RUM、Log、Trace 或 Replay 采样率越界
`captureFps must be an integer between 1 and 5`	Replay FPS 不是 `1–5` 的整数
`maxImageDimension must be between 1 and 2048`	Replay 最长边越界
`... must not be empty`	View、Action、Resource Key 或 Trace URL 等必填字符串为空

性能问题¶

Session Replay 从 captureFps: 1、maxImageDimension: 720 开始。
不需要时关闭 Console 自动采集。
避免在日志和事件属性中传入大型对象。
只启用需要的 Native 监控指标。
检查是否存在重复网络采集。

关闭 SDK 后不再采集¶

guanceSdk.shutdown() 会移除自动监听、停止 Session Replay 并关闭 Native SDK。关闭后不要继续调用采集方法；如需重新启用，建议重新启动应用并完成一次初始化。