报错参考

系统与框架级报错

系统框架、热更新、版本检查、底层通信等可能出现的报错、解决方案及说明

本文档汇总 AstroBox 在系统框架、热更新、版本检查、前后端通信等底层流程中可能向用户展示的报错信息。常见报错与解决方案已置顶，完整清单见文末。

常见报错与解决方案

account.sessionExpired（账号会话过期）

报错原文

account.sessionExpired

触发场景：ACCOUNT_SESSION_EXPIRED_EVENT 事件触发，账号会话已过期。

解决方案：重新登录 AstroBox 账号。

源码位置：App.tsx:384

update.toast.checkFailed（更新检查失败）

报错原文

update.toast.checkFailed

触发场景：检查应用更新失败（网络异常或更新服务器不可达）。

解决方案：检查网络连接，或稍后重试。

源码位置：pages/settings/about/index.tsx:618

settings.sponsorPlan.iapPurchaseFailed（内购购买失败）

报错原文

settings.sponsorPlan.iapPurchaseFailed + <error>

触发场景：App Store 购买失败（StoreKit 错误），常见于支付账户异常或网络问题。

解决方案：检查 App Store 账户状态，或稍后重试。

源码位置：pages/settings/sponsorPlan.tsx:1347

settings.sponsorPlan.iapVerifyPendingRetry（验证暂态重试）

报错原文

settings.sponsorPlan.iapVerifyPendingRetry

触发场景：购买验证遇到暂时性错误，应用会自动重试。

解决方案：等待验证完成，不要关闭应用。

源码位置：pages/settings/sponsorPlan.tsx:1340

NTP query failed（时间同步失败）

报错原文

NTP query failed ({server}): `{err}`

触发场景：设备时间同步（NTP）查询失败。

解决方案：检查网络连接，或手动设置时间。

源码位置：frontapi/device/sync.rs:71

app is not ready（应用未就绪）

报错原文

app is not ready

触发场景：应用初始化完成前调用本地 API / ServerLink 接口。

解决方案：等待应用完全启动后再操作。

源码位置：local_api/handlers.rs:81/130/179/249/643/676/709/744

Invalid version response format（版本响应格式无效）

报错原文

Invalid version response format

触发场景：更新检查返回的版本响应格式无法解析。

解决方案：更新服务器可能临时异常，稍后重试。

源码位置：logic/appUpdate.ts:114

报错原文

Invalid deeplink payload / Missing resource id or provider / Missing plugin name / Unknown deeplink target

触发场景：通过深度链接（URL scheme）打开应用时，payload 无效、缺少资源 ID、缺少插件名或目标未知。

解决方案：确认链接完整有效；如从网页点入，可尝试重新打开链接。

源码位置：backendHandlers.ts:220/227/238/243

完整报错清单

一、Toast 弹窗报错

全局/框架级

触发位置消息说明
App.tsx:384message（ACCOUNT_SESSION_EXPIRED_EVENT payload，或回退到 account.sessionExpired）账号会话过期事件
App.tsx:235translate(messageKey)（网络账号源自动切换提示）启动时自动切换账号源

关于页面 - 更新检查

触发位置消息 Key说明
pages/settings/about/index.tsx:614update.toast.noUpdate无可用更新
pages/settings/about/index.tsx:618update.toast.checkFailed更新检查失败

赞助计划 - IAP

触发位置消息 Key说明
pages/settings/sponsorPlan.tsx:713settings.sponsorPlan.trialLoginRequired试用领取未登录
pages/settings/sponsorPlan.tsx:724settings.sponsorPlan.trialClaimedCreator Pro 试用领取成功
pages/settings/sponsorPlan.tsx:732settings.sponsorPlan.trialAlreadyUsed已使用过试用
pages/settings/sponsorPlan.tsx:736settings.sponsorPlan.trialClaimFailed试用领取其他失败
pages/settings/sponsorPlan.tsx:1273settings.sponsorPlan.iapTransferred订阅转移成功
pages/settings/sponsorPlan.tsx:1276settings.sponsorPlan.iapTransferFailed订阅转移失败
pages/settings/sponsorPlan.tsx:1286settings.sponsorPlan.trialLoginRequiredAppStore 购买未登录
pages/settings/sponsorPlan.tsx:1308settings.sponsorPlan.iapPending购买挂起中
pages/settings/sponsorPlan.tsx:1312settings.sponsorPlan.iapMissingTransaction响应中无交易记录
pages/settings/sponsorPlan.tsx:1321settings.sponsorPlan.iapActivated / iapAlreadyActivated验证通过/已激活
pages/settings/sponsorPlan.tsx:1333settings.sponsorPlan.iapRevoked / iapFailed验证终端失败
pages/settings/sponsorPlan.tsx:1340settings.sponsorPlan.iapVerifyPendingRetry验证暂态重试
pages/settings/sponsorPlan.tsx:1347settings.sponsorPlan.iapPurchaseFailed + errorStoreKit 购买失败
pages/settings/sponsorPlan.tsx:1370settings.sponsorPlan.trialLoginRequired恢复购买未登录
pages/settings/sponsorPlan.tsx:1388settings.sponsorPlan.iapRestoreDone恢复购买成功
pages/settings/sponsorPlan.tsx:1394settings.sponsorPlan.iapFailed恢复购买暂态错误
pages/settings/sponsorPlan.tsx:1396settings.sponsorPlan.iapRestoreEmpty恢复购买无授权
pages/settings/sponsorPlan.tsx:1401settings.sponsorPlan.iapFailed恢复购买失败
pages/settings/sponsorPlan.tsx:1426settings.sponsorPlan.iapActivated未完成交易自动授权

二、Rust 后端返回错误

App 生命周期/调试

位置错误消息触发条件
frontapi/app.rs:118build.devUrl is required in debug desktop mode桌面调试模式缺少 devUrl
frontapi/app.rs:121build.devUrl has no valid host/port: {url}devUrl 解析失败
frontapi/app.rs:162dev server {addr} is unavailable...开发服务器不可达
frontapi/app.rs:209failed to probe dev server after spawn开发服务器启动后探测失败

热更新

所有热更新命令（hotupdate_status, hotupdate_check, hotupdate_apply, hotupdate_bootstrap, hotupdate_confirm_healthy, hotupdate_take_update_note, hotupdate_rollback, hotupdate_pull_patch）均返回 Result<..., String>，使用 .map_err(|e| e.to_string())。用户可见消息由 manager.rs 和 store.rs 生成。

固件/应用更新

位置错误消息触发条件
frontapi/device/update.rs:89persist_device_version_snapshot 错误版本快照保存失败
frontapi/device/update.rs:121Device info response not received: {err:?}设备信息获取失败
frontapi/device/update.rs:158Watchface list response not received: {err:?}表盘列表获取失败
frontapi/device/update.rs:214-223... response not received: {err:?}更新检查查询失败
frontapi/device/update.rs:243Failed to load device version snapshots: {err:?}快照加载失败
frontapi/device/update.rs:255Failed to store device version snapshots: {err:?}快照存储失败
frontapi/device/update.rs:326format_anyhow(&err)更新通用错误

设备同步

位置错误消息触发条件
frontapi/device/sync.rs:63manual input missing手动同步验证失败
frontapi/device/sync.rs:71NTP query failed ({server}): {err}NTP 同步失败

传输诊断

位置错误消息触发条件
frontapi/device/transport_diag.rsformat_anyhow(&err)传输状态/BLE/SPP/清除诊断失败

核心错误格式化

位置功能说明
modules/core/src/error.rsformat_anyhow(err: &anyhow::Error) -> String渲染完整 Caused by: 链和可选回溯，被多个 frontapi 命令消费

FrontBridge 通信层

位置错误消息触发条件
modules/frontbridge/src/lib.rs:158frontend invoke {method} dropped without response前端调用 Rust 后 oneshot channel 被丢弃
modules/frontbridge/src/lib.rs:164-167frontend invoke {method} failed: {error}前端显式报告 success: false

三、WASM / 逻辑层抛错

位置错误消息触发条件
logic/appUpdate.ts:114Invalid version response format版本响应格式无效
logic/stats/storage.ts:214Unable to collect legacy stats from localStorage: ${error}旧版统计数据收集失败
backendHandlers.ts:220Invalid deeplink payload深度链接 payload 无效
backendHandlers.ts:227Missing resource id or provider深度链接缺少资源 ID 或提供商
backendHandlers.ts:238Missing plugin name深度链接缺少插件名
backendHandlers.ts:243Unknown deeplink target未知深度链接目标

四、本地 API / ServerLink

位置错误消息触发条件
local_api/handlers.rs:35unsupported sort: {other}排序验证
local_api/handlers.rs:81/130/179/249/643/676/709/744app is not readyServerLink 应用未就绪

五、其他排查建议

报错建议操作
settings.sponsorPlan.trialLoginRequired先登录 AstroBox 账号
frontend invoke ... dropped without response检查应用是否被系统挂起，重启应用
Failed to load device version snapshots检查存储权限，或重启应用

设置与工具报错

设置页面、高级工具、文件选择器等可能出现的报错、解决方案及说明

社区与社交功能报错

资源评论、评分、举报、收件箱等社交功能可能出现的报错、解决方案及说明

大纲

常见报错与解决方案account.sessionExpired（账号会话过期）update.toast.checkFailed（更新检查失败）settings.sponsorPlan.iapPurchaseFailed（内购购买失败）settings.sponsorPlan.iapVerifyPendingRetry（验证暂态重试）NTP query failed（时间同步失败）app is not ready（应用未就绪）Invalid version response format（版本响应格式无效）Invalid deeplink payload（深度链接无效）完整报错清单一、Toast 弹窗报错全局/框架级关于页面 - 更新检查赞助计划 - IAP二、Rust 后端返回错误App 生命周期/调试热更新固件/应用更新设备同步传输诊断核心错误格式化FrontBridge 通信层三、WASM / 逻辑层抛错四、本地 API / ServerLink五、其他排查建议