故障排查与常见问题

先定位卡在哪一步

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

设备收不到更新

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

bundleStatus: unknownBundle 指向基线匹配问题，重复发布不能解决。rebuiltSameJs 表示相同 JS、不同构建身份，可走全量回退。见 CheckResult。

已下载，页面还是旧的

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

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

启动后回退或白屏

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

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

CLI 未登录、卡住或找不到应用

• 用 me 验证身份；自托管先设置 RNU_SERVICE_URL 再登录，凭据按服务隔离。

• 在含 update.json 的应用根目录执行；本地通过 selectApp --platform android 选平台。

• CI 需要 PAKTA_API_TOKEN、明确目标与 --no-interactive，不能依赖交互选择。

• 参数无法识别时查 CLI；提交 lockfile 让本地与 CI 版本一致。

常见问题

Expo Go 能用吗？

不能。需要包含原生模块的构建，见 Expo 接入。

哪些变更要发原生包？

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

update.json 会进入 App 吗？

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

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

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

自托管怎么配置？

见自托管设置。配额取决于部署的服务端配置，不能假定无限制。

使用 OTA 就能通过审核吗？

不能保证。技术支持不等于审核许可。Apple 对下载执行改变功能的代码有限制，应核对官方审核指南。渠道隔离不是规避审核的保证。

仍无法解决时

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