故障排查¶

SDK 初始化异常¶

普通 uni-app¶

1. 确认 GC-JSPlugin 与 GC-UniPlugin 均为 0.3.0 或更高版本，版本号一致且来自同一发布包。
2. 确认应用入口已在首次使用 JS 采集器前加载 GC-UniPlugin/setup.js。
3. 确认 SDK API 从 GC-UniPlugin 导入，JS 采集器从 GC-JSPlugin 导入。
4. 确认项目中不存在旧的 nativeplugins/GCUniPlugin 及对应 manifest.json 配置。
5. 确认 datakitUrl 或 datawayUrl + clientToken 配置有效。

uni 小程序¶

1. uni 小程序项目只安装 GC-JSPlugin，不导入 GC-UniPlugin 或 setup.js。
2. 宿主 App 在打开 uni 小程序前完成 Native SDK 初始化。
3. 宿主已注册 GCUniPlugin-MobileAgent、GCUniPlugin-RUM、GCUniPlugin-Logger、GCUniPlugin-Tracer。
4. 普通调试基座没有宿主模块时，公共 API 会安全降级为空操作，因此不会上报原生数据；请在真实宿主 App 中完成联调。

开启 Debug 调试¶

普通 uni-app：

import { mobileAgent } from '@/uni_modules/GC-UniPlugin';

mobileAgent.sdkConfig({
    datakitUrl: 'YOUR_DATAKIT_URL',
    debug: true
});

uni 小程序由宿主 App 开启 Native SDK Debug 配置，不在 JS 侧重复调用 sdkConfig()。

发布正式版本前建议关闭 Debug。

SDK 正常运行但没有数据¶

• 排查 Datakit 是否正常运行；
• 确认 SDK 上传地址配置正确，并检查 Debug 日志中的同步结果；
• 确认 RUM 初始化使用了当前平台对应的 App ID；
• 确认当前网络可以访问 Datakit 或 DataWay；
• uni 小程序场景确认宿主 App 初始化完成后才打开 uni 小程序。

数据丢失¶

• 检查 RUM、Log、Trace 中是否配置了 sampleRate < 1；
• Resource 与 Action 需要关联有效 View，确认已通过自动或手动方式调用 startView；
• iOS 开启 enableNativeUserResource 时，gcResourceTracking.startTracking({ enableIOS: false })，避免同一请求重复采集；
• 不要同时启用 gcViewTracking 与旧版 View mixin 采集同一页面；
• 检查设备网络、Datakit 负载及本地缓存限制。

更多相关内容¶

• Android 故障排查
• iOS 故障排查