# 错误处理与排障

## 公共错误码

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

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

示例：

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

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

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

1. 确认 `src/assets/config/` 只有一个 `.xuqmconfig`。
2. 确认 Metro 只使用一个 Xuqm 包装器。
3. 确认配置来自当前公有化或私有化租户平台，不能混用。
4. 查看 `XuqmSDK.getInitializationState()`。
5. 检查租户平台是否已开启对应服务。
6. 如果服务要求登录，确认已经调用公共 `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 不替宿主决定是否允许移动网络下载。

## 插件打不开

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

## BugCollect 没有数据

确认：

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

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

## XWebView 摄像头或麦克风失败

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

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

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

## Push 没有通知

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

## 从历史接入方式迁移

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

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

迁移步骤：

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

## 提交问题时提供

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

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