故障排查¶

本文用于提供 HarmonyOS SDK 初始化和上报异常时的基础排查入口。

初始化失败¶

如果 SDK 初始化失败，建议优先检查：

datakitUrl、datawayUrl、clientToken 是否按部署方式正确配置
ft_sdk.har、ft_native.har 是否已正确放入 libs 目录，并在 oh-package.json5 中分别声明为 @guancecloud/ft_sdk、@guancecloud/ft_native 后执行 ohpm install
应用是否已按文档完成 oh-package.json5 依赖声明
SDK 初始化是否发生在应用启动阶段

建议按以下顺序排查：

如果使用 @kit.NetworkKit 的 HttpInterceptorChain 自动采集未生效，建议优先检查：

当前设备或编译目标是否为 HarmonyOS API 22 及以上；低于 API 22 时不支持该能力
项目是否已安装 ft_sdk.har 和 ft_sdk_ext.har，并在 oh-package.json5 中声明为 @guancecloud/ft_sdk 和 @guancecloud/ft_sdk_ext 后完成 ohpm install
是否已开启 setEnableTraceUserResource(true)；如需自动注入 Trace Headers，还需开启 Trace 配置中的 setEnableAutoTrace(true)
已知在 @kit.NetworkKit 的并发请求场景下，即使为每个请求分别创建独立的 HttpRequest 和 HttpInterceptorChain，仍可能触发异常：{"code":2300003,"message":"Invalid URL format or missing URL"}
如果遇到上述错误，建议优先降级为串行验证；并发场景下可改用 RCP 或 Axios 兼容模式，或暂时避免在高并发链路中使用 HttpInterceptorChain

如果 HTTP 请求已经创建并挂载自动采集拦截器，但 SDK 初始化和 RUM 配置在后执行，可能出现请求成功但 Resource 数据没有生成。

建议优先检查：

是否先创建了 HttpRequest、调用了 createFTHttpInterceptorChain() 或 applyFTHttpTrack()，后面才执行 FTSDK.installRUMConfig()
是否已在 RUM 配置中开启 setEnableTraceUserResource(true)

原因说明：

建议处理方式：

先完成 FTSDK.install()、FTSDK.installRUMConfig()，再创建 HttpRequest 并挂载 HttpInterceptorChain
如果请求对象或拦截器链已提前创建，需要在 SDK 初始化完成后重新创建并重新挂载
如果确实需要在 SDK 初始化前先创建自动采集对象，可在创建时显式传入开关，避免依赖默认配置值

可选写法示例：

applyFTAxiosTrack(client, {
  enableTraceInterceptor: true,
  enableResourceInterceptor: true
});

sdk.init();

注意：

类似处理方式同样适用于 RCP 与 HttpInterceptorChain：

Axios：applyFTAxiosTrack(client, { enableTraceInterceptor: true, enableResourceInterceptor: true })
RCP：createFTRCPInterceptors(true, true) 或 createFTRCPTrackConfig({ enableTraceInterceptor: true, enableResourceInterceptor: true })
HTTP：createFTHttpInterceptorChain({ enableTraceInterceptor: true, enableResourceInterceptor: true }) 或 applyFTHttpTrack(request, { enableTraceInterceptor: true, enableResourceInterceptor: true })