# 故障排查与常见问题

从你看到的现象出发，按顺序检查，并明确下一步该做什么。

## 先定位卡在哪一步 {#technical}

先记录原生版本、当前 hash、渠道、设备 ID 与发生时间。不要一上来重装 App，否则会清除本地更新状态，掩盖问题。

## 设备收不到更新 {#no-update}

按顺序检查，修复一项后重新检查更新：

| 顺序 | 检查什么 | 不符合时怎么做 |
| --- | --- | --- |
| 1 | Release 关闭 Metro 仍能启动 | 按安装页接入原生入口并重新构建 |
| 2 | SDK appKey 与 CLI 应用、平台一致 | 运行 `pakta me`，核对配置 |
| 3 | 手机这份原生包已登记 | 上传同一份构建，不用重打的包替代 |
| 4 | 渠道、原生版本匹配在线投放 | 核对包内渠道，不把更新名称当原生版本 |
| 5 | 应用、渠道、原生包与投放状态正常 | 检查暂停或过期状态 |
| 6 | 测试设备命中灰度 | 独立测试应用用 100%；生产未命中可能正常 |
| 7 | 更新接口与制品地址可达 | 自托管分别检查 SDK `/api` 和 CLI 服务主机 |

`bundleStatus: unknownBundle` 指向基线匹配问题，重复发布不能解决。`rebuiltSameJs` 表示相同 JS、不同构建身份，可走全量回退。见 [CheckResult](/docs/api#check-result)。

## 已下载，页面还是旧的 {#activation}

`download_success` 只说明下载完成。`silentAndLater` 需要下载后彻底退出进程、再次启动；切后台再回来通常只是触发检查。

如果 `currentHash` 变了但文字没变，检查 `.ppk` 的入口、分支与打包内容。发布名称变化不代表内容变化。

## 启动后回退或白屏 {#rollback}

暂停放量，保留问题版本与 sourcemap。读取 `getUpdateMetadata()` 的 `isRolledBack`、`rolledBackVersion`、`currentVersion`，按[错误诊断](/docs/errors)还原堆栈。

未确认健康的更新可在后续启动被保护性回退。确认健康之后的错误不保证触发自动回退，需[重新投放历史稳定包](/docs/publish#rollback)，并复查关键初始化与确认时机。

## CLI 未登录、卡住或找不到应用 {#cli}

- 用 `me` 验证身份；自托管先设置 `RNU_SERVICE_URL` 再登录，凭据按服务隔离。
- 在含 `update.json` 的应用根目录执行；本地通过 `selectApp --platform android` 选平台。
- CI 需要 `PAKTA_API_TOKEN`、明确目标与 `--no-interactive`，不能依赖交互选择。
- 参数无法识别时查 [CLI](/docs/cli)；提交 lockfile 让本地与 CI 版本一致。

## 常见问题 {#business}

### Expo Go 能用吗？

不能。需要包含原生模块的构建，见 [Expo 接入](/docs/getting-started#expo)。

### 哪些变更要发原生包？

原生依赖、权限、原生代码与运行时变化。OTA 只投放兼容现有原生能力的 JS 与资源，见[更新边界](/docs/introduction#boundaries)。

### update.json 会进入 App 吗？

CLI 用它保存 appId/appKey。业务代码 import 后，内容会进入 bundle；未导入时只是发布配置。不能存放发布令牌。

### 暂停或删除投放会撤销已安装更新吗？

不会。它们改变后续分发，已安装内容需要新的恢复投放和设备激活。缩小比例同样不会主动回退。

### 自托管怎么配置？

见[自托管设置](/docs/getting-started#self-host)。配额取决于部署的服务端配置，不能假定无限制。

### 使用 OTA 就能通过审核吗？

不能保证。技术支持不等于审核许可。Apple 对下载执行改变功能的代码有限制，应核对[官方审核指南](https://developer.apple.com/app-store/review/guidelines/#software-requirements)。渠道隔离不是规避审核的保证。

## 仍无法解决时 {#support}

提交问题时附：平台与 RN/Expo/SDK/CLI 版本、原生版本、渠道、当前更新 hash、投放 ID、失败阶段、发生时间和脱敏堆栈。不要附令牌、密码或会话配置。