错误处理与排障

公共错误码

需要初始化的扩展能力可能抛出 XuqmError：

错误码	含义	宿主处理
`XUQM_NOT_READY`	自动初始化尚未完成或没有启动	检查配置和 Metro；不要阻断宿主首页
`XUQM_NOT_LOGGED_IN`	当前操作要求登录	完成宿主登录后重试
`XUQM_CONFIG_INVALID`	配置格式或签名无效	重新从租户平台下载配置并构建
`XUQM_CONFIG_EXPIRED`	构建使用的配置已过期	重新生成并构建
`XUQM_CONFIG_REVOKED`	配置已被租户平台撤销	使用平台当前有效配置重新构建
`XUQM_SERVICE_DISABLED`	对应服务未开启	隐藏入口或跳过功能

示例：

import { XuqmError } from '@xuqm/rn-common'

try {
  await operation()
} catch (error) {
  if (error instanceof XuqmError) {
    reportNonBlockingError(error.code)
    return
  }
  throw error
}

App 启动正常，但扩展功能不可用

确认 src/assets/config/ 只有一个 .xuqmconfig。
确认 Metro 只使用一个 Xuqm 包装器。
确认配置来自当前公有化或私有化租户平台，不能混用。
查看 XuqmSDK.getInitializationState()。
检查租户平台是否已开启对应服务。
如果服务要求登录，确认已经调用公共 login。

扩展服务失败不应导致宿主白屏。不要在根组件渲染前无限等待网络初始化。

Common-only 工程提示未初始化

Common 的网络、文件、时间和 UI 能力不要求初始化。出现未初始化错误通常表示调用了需要平台配置的扩展 API，或直接调用了 getConfig()。

Common-only 工程应当：

不放 .xuqmconfig。
不使用 Metro 自动配置包装器。
不调用 XuqmSDK.awaitInitialization()。
业务网络使用绝对 URL 或 configureHttp。

配置构建失败

构建期失败是预期的安全门禁，常见原因：

配置文件超过一个。
文件内容被编辑、损坏或不属于当前应用。
配置过期或已撤销。
公有化配置用于私有化应用，或反向混用。

不要通过跳过校验生成安装包，应从租户平台重新下载配置。

Update 不弹更新

先检查 checkAppUpdate() 的结构化状态：

LOGIN_REQUIRED：未登录时正常跳过。
SERVICE_DISABLED：租户平台未启用 Update。
NO_UPDATE：没有适用于当前版本、设备或灰度身份的更新。
FAILED：查看 errorCode 和 message，但不要阻断应用。

网络状态随检查结果返回，SDK 不替宿主决定是否允许移动网络下载。

插件打不开

Debug 确认 Metro 属于当前工程并能正常 Fast Refresh。
运行 pnpm run xuqm:doctor。
确认模块 ID 与 xuqm.modules.json 一致。
检查插件入口是否调用 definePlugin。
更新检查失败时，确认宿主仍会尝试打开本地版本。
只有插件实际启动失败才记录启动失败，网络检查失败不是插件启动失败。

BugCollect 没有数据

确认：

用户已经同意隐私声明。
租户平台已开启 BugCollect。
当前不是默认禁止自动上报的 Debug 行为。
Release 构建没有启用应急关闭。
测试页调用 sendTestErrorAndFlush 时能看到明确错误。

BugCollect 失败不能影响宿主功能，不要通过抛出全局异常验证生产采集。

XWebView 摄像头或麦克风失败

同时满足以下条件才会授权：

宿主声明并获得系统权限。
permissions.camera 或 permissions.microphone 已开启。
当前网页 Origin 精确命中 allowedOrigins。
自定义 onRequest 没有拒绝。

协议、端口或子域名变化都会形成不同 Origin。

Push 没有通知

检查系统通知权限、设备厂商通道、包名与签名、租户平台服务状态、用户离线推送开关和免打扰时间。RN 页面不应以是否缓存到厂商 Token 判断最终绑定状态。

从历史接入方式迁移

当前版本不再使用以下方式：

手动传 AppKey 初始化。
页面或子模块分别初始化、登录。
宿主手工传入应用商店地址。
Update 的旧 Bundle 下载与应用方法。
RN 页面手工注册推送 Token。
XWebView 的扁平参数和全局控制器。

迁移步骤：

下载并放置唯一配置文件。
使用一个 Metro 包装器。
隐私授权同步一次。
登录和登出只调用 Common。
按本文各模块页面替换旧 API。
删除宿主重复的 SDK 状态、地址和 Token 缓存。

提交问题时提供

SDK 包名与精确版本。
React Native、Android/iOS 和设备系统版本。
公有化或私有化类型，不提供服务端秘密。
初始化状态、结构化错误码和最小复现路径。
已脱敏日志。

不要上传 .xuqmconfig、Token、用户隐私数据或完整业务响应。

4.8 KiB 原始文件 Blame 文件历史 Unescape Escape