143 行
4.8 KiB
Markdown
143 行
4.8 KiB
Markdown
# 错误处理与排障
|
||
|
||
## 公共错误码
|
||
|
||
需要初始化的扩展能力可能抛出 `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、用户隐私数据或完整业务响应。
|
