主题
AstroBox 报错参考
AstroBox 各功能模块的报错信息汇总及排查建议
报错参考
本文档分类汇总 AstroBox 在各功能模块中可能向用户展示的报错信息，涵盖 Toast 弹窗、队列内嵌错误、Rust 后端返回错误、WASM / 逻辑层抛错及常见排查建议。点击下方卡片查看对应分类的详细报错说明。
| 报错 | 描述 |
|---|---|
| 设备连接报错 | 蓝牙扫描、设备连接、SPP 通信等环节的报错信息 |
| 资源下载报错 | 官方源、三方源、加密资源下载等流程的报错信息 |
| 资源安装报错 | 资源安装、队列推送、插件安装等流程的报错信息 |
| 账号系统报错 | 小米/vivo 账号登录、AstroBox 账号管理的报错信息 |
| 音乐管理报错 | 音乐导入、歌单创建/编辑/删除等流程的报错信息 |
| 表盘编辑报错 | 表盘编辑、自定义文本、字体选择、应用等环节的报错信息 |
| 插件系统报错 | 插件安装、启用、禁用、卸载等流程的报错信息 |
| 设置与工具报错 | 设置页面、高级工具、文件选择器、缓存清理等报错信息 |
| 系统与框架级报错 | 系统框架、热更新、版本检查、前后端通信等报错信息 |
| 社区与社交功能报错 | 资源评论、评分、举报、收件箱、个人资料等报错信息 |
设备连接报错
常见报错与解决方案
连接失败：Auth HMAC mismatch, This usually means your AuthKey is wrong.
报错原文
连接失败：Auth HMAC mismatch, This usually means your AuthKey is wrong.（日志末尾可能附带 Backtrace capture disabled. Set RUST_LIB_BACKTRACE=1 to enable. 提示，这是 Rust 的调试提示，不是报错本身。）
触发场景：连接设备时 AuthKey 错误，设备拒绝握手。
解决方案：AuthKey 错误，请重新从小米账号获取，或重新确认 AuthKey 的有效性。
源码位置：modules/core/src/device/xiaomi/components/auth.rs:254
vivo file_v2: send ack receiver dropped
报错原文
vivo file_v2: send ack receiver dropped触发场景：vivo 设备传输过程中发送 ACK 确认时接收端已关闭，通常由设备断联导致。
解决方案：设备断联，检查设备连接状态，重新连接后重试。
源码位置：modules/core/src/device/vivo/components/file_v2_transfer.rs:533
failed to decode reverse MASS packet: block 3 was not found!
报错原文
bash
failed to decode reverse MASS packet: <底层错误>
# 或
failed to assemble reverse MASS payload: block N was not found!触发场景：拉取日志（或设备→App 方向的数据传输）时手表侧丢包，导致 MASS 分片重组失败。注意两条错误链独立存在：failed to decode reverse MASS packet 包裹的是底层包错误（如 Invalid reverse mass packet / Invalid crc32），block N was not found! 单独出现在分片缺块时，外层为 failed to assemble reverse MASS payload。
解决方案：原因不明，拉取之前先重启设备、清理手表内存会好一点。
源码位置：modules/core/src/device/xiaomi/components/mass.rs:251（decode context）、modules/core/src/device/xiaomi/packet/mass.rs:215（block not found）
Device connect timed out
报错原文
Device connect timed out触发场景：设备未在预期时间内完成连接握手（常见于设备处于其他配对模式、或蓝牙信号弱）。
解决方案：检查设备是否处于「连接新手机」/配对模式，确认蓝牙权限已授予，然后重试连接。
源码位置：frontapi/device.rs:532
Device connect canceled
报错原文
Device connect canceled触发场景：用户在连接过程中主动取消（例如切换页面、关闭连接弹窗）。
解决方案：重新点击连接，避免操作过程中切换页面。
源码位置：frontapi/device.rs:528
完整报错清单
一、Toast 弹窗报错
1. 无可用设备
| 触发位置 | 消息 Key | 说明 |
|---|---|---|
| logic/deviceConnectionGuard.ts | device.connect.noDevice | 当前无已连接设备时触发，多处调用（队列安装、音乐导入、传输诊断、日志获取等） |
| logic/queue/installhelper.ts:262 | device.connect.noDevice | 安装任务创建时检测到无设备 |
| logic/queue/musichelper.ts:120 | device.connect.noDevice | 音乐上传任务创建时检测到无设备 |
| pages/settings/extratools.tsx | device.noDevice | 打开设备信息、开始/停止抓包、运行冒烟测试、获取日志时无设备 |
2. 连接失败
| 触发位置 | 消息 | 说明 |
|---|---|---|
| logic/device.ts:233 | device.connect.fail: ${message} 或 device.connect.fail | 连接设备失败（排除 iOS TargetRejected 情况） |
| components/nav/NavDeviceCard.tsx:110 | device.wasm.missingAuth | WASM 运行时缺少 Authkey |
二、Rust 后端返回错误
1. 蓝牙扫描
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| frontapi/bluetooth.rs | ScanError::AdapterNotFound | 开始/停止扫描时未找到蓝牙适配器 |
2. 设备连接核心
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| frontapi/device.rs:493 | 蓝牙连接错误详情 | 设备连接时蓝牙层失败 |
| frontapi/device.rs:520 | format_anyhow(&err) | 设备连接通用失败（含完整错误链） |
| frontapi/device.rs:524 | Device connect failed | 设备连接失败 |
| frontapi/device.rs:528 | Device connect canceled | 用户主动取消连接 |
| frontapi/device.rs:532 | Device connect timed out | 设备连接超时 |
3. SPP 插件层连接错误
| 平台 | 错误消息 | 触发条件 |
|---|---|---|
| btclassic-spp/macos | Connection closed | 连接关闭 |
| btclassic-spp/macos | RFCOMM send already in progress | RFCOMM 发送冲突 |
| btclassic-spp/macos | RFCOMM send timed out | RFCOMM 发送超时 |
| btclassic-spp/macos | RFCOMM channel disconnected | RFCOMM 通道断开 |
| btclassic-spp/win | Socket error: | Socket 错误 |
| btclassic-spp/win | Connection closed by peer | 对端关闭连接 |
| btclassic-spp/win | Bluetooth is not available | 蓝牙不可用 |
| btclassic-spp/win | No Bluetooth adapter found | 未找到蓝牙适配器 |
| btclassic-spp/linux | Connection closed / BlueZ/DBus 错误 | Linux 蓝牙连接错误 |
| btclassic-spp/desktop.rs | corelib::anyhow_site!(...) | 桌面端 SPP 错误转发 |
| btclassic-spp/mobile.rs | Deserialize error from mobile: | 移动端数据反序列化失败 |
| btclassic-spp/mobile.rs | {err_msg} (Android msg.err) | SPP 读取错误 |
| btclassic-spp/mobile.rs | Base64 decode error from mobile: | Base64 解码失败 |
三、WASM / 逻辑层抛错
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| ipc/wasmBridge.ts:9 | WASM bridge requested outside wasm runtime | 非 WASM 环境调用 WASM bridge |
| ipc/wasmBridge.ts:170 | Unsupported command in wasm runtime: | WASM 不支持该命令 |
四、队列内嵌报错（progressDesc）
连接相关错误被 taskList.ts 捕获后，以红色文字写入任务卡片的 progressDesc：
| 报错 | 说明 |
|---|---|
| device.connect.noDevice | 常见于安装/音乐任务开始时检测到无设备连接 |
五、其他排查建议
| 报错 | 建议操作 |
|---|---|
| device.connect.noDevice | 确保设备已连接，检查设备卡片状态 |
| ScanError::AdapterNotFound | 检查设备蓝牙是否开启，桌面端检查蓝牙驱动/权限 |
| RFCOMM channel disconnected (macOS) | 忽略设备后重新配对，或重启 AstroBox |
| TargetRejected (iOS) | 前往系统设置-蓝牙中忽略对应设备后重试 |
| device.wasm.missingAuth | WASM 模式下确保已填写 Authkey/OpenID |
资源下载报错
资源下载流程中可能出现的报错、解决方案及说明
本文档汇总 AstroBox 在从官方源、三方源、加密资源下载等流程中可能向用户展示的报错信息。常见报错与解决方案已置顶，完整清单见文末。
常见报错与解决方案
resource.purchase.invalidSignature（加密资源签名无效）
报错原文
resource.purchase.invalidSignature触发场景：请求加密资源信息失败（非 file_not_found 时），或解密后校验签名不通过。
解决方案：确认已购买该资源，或重新登录账号刷新授权；如仍失败请联系资源作者。
源码位置：logic/queue/downloadhelper.ts:543（maybeResolveEncryptedResourceFile）
resource_crypto_hash_mismatch（加密资源哈希不匹配）
报错原文
resource_crypto_hash_mismatch触发场景：加密资源解密后哈希校验不通过，资源文件可能在传输中损坏。
解决方案：尝试重新下载资源；如反复失败请联系资源作者确认文件完整性。
源码位置：logic/resourceCrypto.ts:43
resource.purchase.decryptFailed（资源解密失败）
报错原文
resource.purchase.decryptFailed触发场景：commprov_resource_file_decrypt 调用失败，资源无法解密。
解决方案：确认网络稳定，或联系资源提供方确认资源状态。
源码位置：logic/queue/downloadhelper.ts:558
No downloadable artifact found
报错原文
No downloadable artifact found触发场景：下载 action 执行时找不到可用下载产物（资源已下架或链接失效）。
解决方案：检查资源是否已下架或链接失效，联系资源作者确认。
源码位置：logic/queue/downloadhelper.ts:114
resource.unknown.type（未知资源类型）
报错原文
resource.unknown.type + <资源名>触发场景：下载完成后 device_get_file_type 返回的类型无法映射，或 manifest.item.restype 无法解析。
解决方案：确认资源文件类型正确，或联系资源作者确认类型声明。
源码位置：logic/queue/downloadhelper.ts:156 / logic/queue/downloadhelper.ts:459
完整报错清单
一、Toast 弹窗报错
下载辅助函数 (downloadhelper)
| 触发位置 | 消息 | 说明 |
|---|---|---|
| logic/queue/downloadhelper.ts:156 | resource.unknown.type + 资源名 | 下载完成后 device_get_file_type 无法映射类型 |
| logic/queue/downloadhelper.ts:459 | resource.unknown.type + 资源名 | manifest.item.restype 无法解析 |
| logic/queue/downloadhelper.ts:543 | localizedMessage（resource.purchase.invalidSignature / hashMismatch / invalidPayload 或原始消息） | 请求加密资源信息失败（非 file_not_found） |
| logic/queue/downloadhelper.ts:558 | resource.purchase.decryptFailed | commprov_resource_file_decrypt 失败 |
| logic/queue/downloadhelper.ts:344 | device.firmware.shared | Tauri 移动端系统分享文件成功 |
| logic/queue/downloadhelper.ts:368 | device.firmware.savedTo + 保存路径 | 桌面端保存成功 |
| logic/queue/downloadhelper.ts:388 | device.firmware.savedTo + 文件名 | Web 端 Blob 下载成功 |
资源详情页 (Hero)
| 触发位置 | 消息 | 说明 |
|---|---|---|
| components/resource/detail/Hero.tsx:381 | resource.purchase.trialDownloadUnavailable | 试用入口无 URL 且无法解析 |
| components/resource/detail/Hero.tsx:395 | err?.message ?? err | 解析试用入口失败 |
| components/resource/detail/Hero.tsx:508 | resource.unavailable | 无外部下载 URL |
| components/resource/detail/Hero.tsx:569 | resource.purchase.emptyCdk | CDK 码为空 |
| components/resource/detail/Hero.tsx:575 | resource.purchase.activateSuccess | CDK 兑换成功 |
| components/resource/detail/Hero.tsx:579 | err?.message ?? err | CDK 兑换失败 |
| components/resource/detail/Hero.tsx:608 | resource.purchase.linkUnavailable | 购买选项无购买链接 |
| components/resource/detail/Hero.tsx:852 | common.copied | 分享链接复制成功 |
| components/resource/detail/Hero.tsx:855 | common.copyFailed | 分享链接复制失败 |
固件页面
| 触发位置 | 消息 | 说明 |
|---|---|---|
| pages/device/firmware.tsx:540 | device.firmware.enqueued | 固件下载并安装入队 |
| pages/device/firmware.tsx:574 | device.firmware.downloadQueued | 全量包下载入队 |
| pages/device/firmware.tsx:607 | device.firmware.downloadQueued | 差分包下载入队 |
二、队列内嵌报错（progressDesc）
taskList.ts 捕获下载 action 异常后写入任务卡片：
| 来源 | 典型错误消息 | 触发场景 |
|---|---|---|
| downloadhelper.ts | No downloadable artifact found | 无可用下载产物 |
| downloadhelper.ts | resource.purchase.invalidSignature | 加密资源签名无效 |
| downloadhelper.ts | resource_crypto_hash_mismatch | 加密资源哈希不匹配 |
| downloadhelper.ts | resource_crypto_invalid_payload | 加密资源无效 payload |
| downloadhelper.ts | resource.purchase.decryptFailed | 资源解密失败 |
| downloadhelper.ts | resource.unknown.type + 资源名 | 下载完成后类型无法识别 |
三、Rust 后端返回错误
社区提供商
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| frontapi/provider.rs:185 | err.to_string() | 提供商分发失败 |
| frontapi/provider.rs:191 | Plugin provider download timed out after {secs}s | 提供商下载超时 |
| frontapi/provider.rs:198 | Plugin provider download failed: | 提供商下载失败 |
| frontapi/provider.rs:294 | Plugin provider download returned an empty result | 空提供商结果 |
| frontapi/provider.rs:418/430/501/530/586/656 | Provider not found | 提供商查找失败 |
| frontapi/provider.rs:691 | Invalid AES-256 key format | 密钥格式验证 |
本地 API / ServerLink 下载
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| local_api/handlers.rs:515 | missing id | 下载验证缺少 ID |
| local_api/handlers.rs:528 | err | 下载错误 |
| local_api/handlers.rs:540 | download entry not found | 下载条目缺失 |
| local_api/handlers.rs:552 | device is required when OfficialV2 download url is unresolved | OfficialV2 下载缺少设备参数 |
| local_api/handlers.rs:570 | err | 下载解析错误 |
| local_api/handlers.rs:583 | download url is unavailable for this provider/item | 下载 URL 不可用 |
图片/数据工具
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| frontapi/utils.rs:14 | fetch error: | 远程数据获取失败 |
| frontapi/utils.rs:18/33 | resource too large | 资源大小超限 |
| frontapi/utils.rs:31 | read error: | 远程数据读取失败 |
四、WASM / 逻辑层抛错
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| logic/queue/downloadhelper.ts:114 | No downloadable artifact found | 无可用下载产物 |
| logic/queue/downloadhelper.ts:323 | Expected temporary file download result in Tauri runtime | Tauri 运行时临时文件结果缺失 |
| logic/queue/downloadhelper.ts:372 | Expected in-memory download result in web runtime | Web 运行时内存结果缺失 |
| logic/queue/downloadhelper.ts:440 | resource.purchase.trialDownloadUnavailable | 试用下载不可用 |
| logic/queue/downloadhelper.ts:544 | localizedMessage（签名/哈希/解密错误） | 加密资源处理失败 |
| logic/queue/downloadhelper.ts:559 | message | 解密失败 |
| logic/resourceCrypto.ts:40 | resource_crypto_invalid_payload | 加密资源无效 payload |
| logic/resourceCrypto.ts:43 | resource_crypto_hash_mismatch | 加密资源哈希不匹配 |
| logic/resourceCrypto.ts:54 | resource_crypto_invalid_signature | 加密资源签名无效 |
| logic/networkHttp.ts:157 | 描述非 JSON 响应体 | HTTP 非 JSON 响应 |
| logic/networkHttp.ts:199/218/236/250/337 | HTTP 错误详情 | HTTP 请求失败 |
| components/resource/detail/Hero.tsx:203 | OfficialV2 device map is not ready | OfficialV2 设备映射未就绪 |
五、其他排查建议
| 报错 | 建议操作 |
|---|---|
| No downloadable artifact found | 检查资源是否已下架或链接失效 |
| Provider not found | 检查社区源配置，或尝试刷新源列表 |
| download url is unavailable | 该资源当前无可用下载链接 |
| resource too large | 资源超过大小限制，联系作者或使用其他渠道 |
| OfficialV2 device map is not ready | 等待设备映射加载完成，或刷新页面 |
资源安装报错
资源安装与队列推送过程中可能出现的报错、解决方案及说明
本文档汇总 AstroBox 在资源安装、队列推送、插件安装等流程中可能向用户展示的报错信息。常见报错与解决方案已置顶，完整清单见文末。
常见报错与解决方案
install result message missing
报错原文
install result message missing触发场景：安装过程中穿戴设备重启或断联，导致安装结果消息丢失。
解决方案：尝试重启安装；如果仍然如此，请确认资源本身是否有问题（文件损坏或不完整）。
源码位置：modules/core/src/device/xiaomi/components/install.rs:226
third-party app install failed: InstallFailed
报错原文
third-party app install failed: InstallFailed触发场景：穿戴设备拒绝了安装，具体原因不明（设备返回 InstallFailed 或 VerifyFailed 状态码）。
解决方案：建议重启穿戴设备和 AstroBox 后再尝试。
源码位置：modules/core/src/device/xiaomi/components/install.rs:397
install prepare failed with status: Downgrade
报错原文
install prepare failed with status: Downgrade触发场景：表盘 ID 冲突（设备上已存在更高版本或相同 ID 的表盘，拒绝降级安装）。
解决方案：更换表盘 ID，或在设置中开启「强制安装表盘」后重试。
源码位置：modules/core/src/device/xiaomi/components/install.rs:207
install prepare failed with status: LowStorage
报错原文
install prepare failed with status: LowStorage触发场景：穿戴设备存储空间不足，或安装的资源数量已达到设备上限。
解决方案：清理设备上的无用资源后再安装。
源码位置：modules/core/src/device/xiaomi/components/install.rs:207
failed to send MASS payload: Mass data prepare was not READY
报错原文
failed to send MASS payload
Caused by: Mass data prepare was not READY触发场景：设备认为当前不具备安装条件（设备处于 Busy / Duplicated / LowStorage / LowBattery / Downgrade 等非 Ready 状态），具体原因不详。
解决方案：建议重启穿戴设备和 AstroBox 后再尝试。
源码位置：modules/core/src/device/xiaomi/components/mass.rs:421，外层 context 在 components/install.rs:214
完整报错清单
一、Toast 弹窗报错
安装队列通用
| 触发位置 | 消息 Key | 说明 |
|---|---|---|
| pages/queue.tsx:146 | plugin.install.unsupported | 非 Tauri 运行时尝试安装插件 |
| pages/plugin/storeDetail.tsx:83 | plugin.install.unsupported | 非 Tauri 环境安装插件 |
安装辅助函数 (installhelper)
| 触发位置 | 消息 | 说明 |
|---|---|---|
| logic/queue/installhelper.ts:169 | queue.watchfaceIdConflict（可附带「覆盖安装」按钮） | 安装表盘时检测到 downgrade 冲突 |
| logic/queue/installhelper.ts:262 | device.connect.noDevice | 无已连接设备 |
| logic/queue/installhelper.ts:448 | resource.firmware.invalid + 文件名（可附带「继续安装」按钮） | 固件文件校验失败 |
| logic/queue/installhelper.ts:532 | resource.unknown.type + 文件名 | 文件扩展名检查不通过 |
| logic/queue/installhelper.ts:555 | plugin.install.unsupported | 非 Tauri 环境安装 ABP |
| logic/queue/installhelper.ts:559 | resource.unknown.type + 文件名 | ABP 文件类型不允许 |
| logic/queue/installhelper.ts:572 | err.message 或 plugin.install.failed | plugsys_install_abp 调用异常 |
| logic/queue/installhelper.ts:619 | resource.unknown.type + 文件名 | detectSelectedFileType 返回 undefined |
| logic/queue/installhelper.ts:623 | resource.unknown.type + 文件名 | 扩展名检查不通过 |
| logic/queue/installhelper.ts:630 | plugin.install.unsupported | ABP 为 Web File 对象（非路径） |
插件操作
| 触发位置 | 消息 | 说明 |
|---|---|---|
| pages/plugin/detail.tsx:344 | plugin.action.enableFailed | 启用插件失败 |
| pages/plugin/detail.tsx:350 | plugin.action.disableFailed | 禁用插件失败 |
| pages/plugin/detail.tsx:356 | err.message / plugin.action.updateFailed | 插件状态切换失败 |
| pages/plugin/detail.tsx:375 | plugin.action.uninstallFailed | 卸载插件失败 |
| pages/plugin/detail.tsx:388 | err.message / plugin.action.uninstallFailed | 卸载插件失败 |
二、队列内嵌报错（progressDesc）
taskList.ts 捕获 action 抛出的异常后，将错误写入任务卡片红色 progressDesc：
| 来源 | 典型错误消息 | 触发场景 |
|---|---|---|
| installhelper.ts | device.connect.noDevice | 安装开始时无设备 |
| installhelper.ts | resource.firmware.invalid | 固件校验失败 |
| installhelper.ts | resource.unknown.type + 文件名 | 文件类型未知 |
| installhelper.ts | plugin.install.unsupported | 插件安装不支持 |
| installhelper.ts | plugin.install.failed | ABP 安装调用失败 |
| pluginhelper.ts | plugin.install.unsupported | 插件安装不支持 |
| pluginhelper.ts | plugin.install.failed: store base empty | 插件存储基础为空 |
三、Rust 后端返回错误
设备安装验证
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| frontapi/device.rs:647 | device_install: either \dataorfile_path is required | 安装参数缺失 |
| frontapi/device.rs:748 | device_install: file type mismatch... | 文件类型不匹配 |
| frontapi/device.rs:764 | device_install: either \dataorfile_path is required | 安装参数缺失 |
插件系统
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| frontapi/plugsys.rs:224 | invalid path component in {relative_path} | 插件路径验证 |
| frontapi/plugsys.rs:284 | store base is empty | 插件存储验证 |
| frontapi/plugsys.rs:325 | manifest entry is empty | 插件清单验证 |
| frontapi/plugsys.rs:474 | Failed to remove plugin directory: | 插件目录移除 |
| frontapi/plugsys.rs:492 | Invalid folder name: path traversal detected | 路径遍历检测 |
| frontapi/plugsys.rs:517 | Failed to remove plugin directory: | 插件目录移除 |
| frontapi/plugsys.rs:566 | Plugin '{name}' is disabled | 插件启动验证 |
| frontapi/plugsys.rs:570 | err.to_string() | 插件启动失败 |
| frontapi/plugsys.rs:577 | Plugin '{name}' is not loaded | 插件未加载 |
| frontapi/plugsys.rs:602 | Plugin '{name}' is disabled | 插件 UI 打开验证 |
| frontapi/plugsys.rs:606 | err.to_string() | 插件 UI 打开失败 |
| frontapi/plugsys.rs:613 | Plugin '{name}' is not loaded | 插件 UI 打开验证 |
| frontapi/plugsys.rs:644 | Plugin '{name}' is not ready | 插件 RPC 验证 |
| frontapi/plugsys.rs:673 | Plugin '{name}' is not ready | 插件状态验证 |
插件平台 Stub
| 插件 | 错误消息 | 触发条件 |
|---|---|---|
| iap/src/error.rs | IAP is not supported on this platform | IAP 平台检查 |
| inappbrowser/src/error.rs | in-app browser is not supported on this platform | 浏览器平台检查 |
| cloud-push/src/stub.rs | cloud push is not supported on this platform | 云推送不支持 |
四、WASM / 逻辑层抛错
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| ipc/wasmBridge.ts:106 | device_install is not implemented for wasm runtime | WASM 不支持 device_install |
| ipc/wasmBridge.ts:114 | device_install in wasm runtime requires binary data | WASM install 缺少数据 |
| ipc/wasmBridge.ts:130 | device_install in wasm runtime expects Uint8Array-compatible data | WASM install 数据类型错误 |
| logic/queue/installhelper.ts:281 | device.connect.noDevice | 安装时无设备 |
| logic/queue/pluginhelper.ts:67 | plugin.install.unsupported | 插件安装不支持 |
| logic/queue/pluginhelper.ts:70 | plugin.install.failed: store base empty | 插件存储基础为空 |
| backendHandlers.ts:220 | Invalid deeplink payload | 深度链接 payload 无效 |
| backendHandlers.ts:227 | Missing resource id or provider | 深度链接缺少资源 ID 或提供商 |
| backendHandlers.ts:238 | Missing plugin name | 深度链接缺少插件名 |
| backendHandlers.ts:243 | Unknown deeplink target | 未知深度链接目标 |
五、本地 API / ServerLink 相关
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| local_api/handlers.rs:98 | missing path | 资源安装路径缺失 |
| local_api/handlers.rs:109 | path must be absolute | 路径非绝对路径 |
| local_api/handlers.rs:119 | path is not a file | 路径不是文件 |
| local_api/handlers.rs:154 | frontend rejected request | 前端拒绝安装请求 |
| local_api/handlers.rs:164 | err.to_string() | ServerLink 入队错误 |
六、其他排查建议
| 报错 | 建议操作 |
|---|---|
| resource.unknown.type | 确认文件扩展名正确，资源文件未损坏 |
| resource.firmware.invalid | 确认固件文件完整，或尝试点击「继续安装」 |
| plugin.install.unsupported | 插件安装仅支持 Tauri 桌面端，Web/WASM 不支持 |
| store base is empty | 检查插件存储目录权限，或重启 AstroBox |
| device.connect.noDevice | 先连接设备再执行安装操作 |
| queue.watchfaceIdConflict | 确认是否覆盖安装，或更换不同 ID 的表盘 |
| Plugin '{name}' is disabled | 先启用插件再执行操作 |
| Plugin '{name}' is not loaded | 检查插件是否正确安装，尝试重新安装 |
账号系统报错
账号登录、绑定、认证过程中可能出现的报错、解决方案及说明
本文档汇总 AstroBox 在小米/vivo 账号登录、AstroBox 账号管理、绑定解绑等流程中可能向用户展示的报错信息。常见报错与解决方案已置顶，完整清单见文末。
常见报错与解决方案
登入失敗：serviceLoginAuth2 returned credential challenge again
报错原文
登入失敗：serviceLoginAuth2 returned credential challenge again; body=xxxxxxxxx触发场景：小米账号登录第二步认证（serviceLoginAuth2）时仍返回凭据校验要求，即登录时账号或密码错误。
解决方案：确认账号密码正确，注意大小写；如忘记密码请先通过小米官方渠道找回。
源码位置：src-tauri/modules/account/src/xiaomi.rs:1593
小米账号登录失败：用户名或密码错误
报错原文
小米账号登录失败：用户名或密码错误触发场景：小米账号用户名或密码错误（API 返回 70016 时同样显示「登录失败：用户名或密码错误」）。
解决方案：确认账号密码正确，注意大小写，或通过小米官方渠道找回密码。
源码位置：frontapi/account.rs:1746 / frontapi/account.rs:2094
原生小米账号登录窗口已在运行，请关闭后重试
报错原文
原生小米账号登录窗口已在运行，请关闭后重试触发场景：登录窗口已打开时再次触发登录。
解决方案：关闭已有的登录窗口后重试。
源码位置：frontapi/account.rs:270
等待小米账号两步验证超时
报错原文
等待小米账号两步验证超时触发场景：两步验证（2FA）页面未在预期时间内完成验证。
解决方案：检查网络连接，确认验证码/二次验证操作已完成，或尝试重新登录。
源码位置：frontapi/account.rs:605 / frontapi/account.rs:824
vivo 登录已完成，但未能从页面或 cookie 中取得 openid
报错原文
vivo 登录已完成，但未能从页面或 cookie 中取得 openid触发场景：vivo 登录流程走完但拿不到 openid，常见于网络异常或页面未正常跳转。
解决方案：检查网络连接，或尝试重新登录。
源码位置：frontapi/account.rs:939
完整报错清单
一、Toast 弹窗报错
AstroBox 账号与绑定
| 触发位置 | 消息 Key | 说明 |
|---|---|---|
| pages/settings/account.tsx:449 | settings.account.bindSuccess | BandBBS 绑定 AstroBox 成功 |
| pages/settings/account.tsx:452 | settings.account.bindFailed + message | BandBBS 绑定失败 |
| pages/settings/account.tsx:493 | settings.account.unbindSuccess | BandBBS 解绑成功 |
| pages/settings/account.tsx:496 | settings.account.unbindFailed + message | BandBBS 解绑失败 |
| guards/BandBbsAuthorizationGuard.tsx:115 | settings.account.bandBbsSyncNetworkError | 同步绑定信息时网络异常（仅 Tauri） |
小米账号
| 触发位置 | 消息 Key | 说明 |
|---|---|---|
| pages/settings/account.tsx:550 | settings.account.xiaomi.importSuccess + count | 小米设备导入成功 |
| pages/settings/account.tsx:557 | settings.account.xiaomi.importFailed + message | 小米设备导入失败 |
| pages/settings/account.tsx:569 | settings.account.xiaomi.logoutSuccess | 小米账号登出成功 |
| pages/settings/account.tsx:572 | settings.account.xiaomi.logoutFailed + message | 小米账号登出失败 |
vivo 账号
| 触发位置 | 消息 Key | 说明 |
|---|---|---|
| pages/settings/account.tsx:589 | settings.account.vivo.loginSuccess | vivo 登录成功 |
| pages/settings/account.tsx:592 | settings.account.vivo.loginFailed + message | vivo 登录失败 |
| pages/settings/account.tsx:604 | settings.account.vivo.logoutSuccess | vivo 登出成功 |
| pages/settings/account.tsx:607 | settings.account.vivo.logoutFailed + message | vivo 登出失败 |
账号注销
| 触发位置 | 消息 Key | 说明 |
|---|---|---|
| pages/settings/accountDeletion.tsx:216 | settings.account.deletion.submitSuccess + ticket id | 注销工单创建成功 |
| pages/settings/accountDeletion.tsx:223 | settings.account.deletion.submitFailed + message | 注销工单创建失败 |
社交限制与封禁
| 触发位置 | 消息 | 说明 |
|---|---|---|
| logic/api/astrobox/request.ts:162 | 你的社交功能已被限制，解除时间：... | 后端返回 social-banned |
| logic/api/astrobox/request.ts:169 | 账号已被封禁：... | 后端返回 user-banned，随后登出 |
| App.tsx:384 | account.sessionExpired | 账号会话过期事件 |
通用复制
| 触发位置 | 消息 Key | 说明 |
|---|---|---|
| pages/settings/account.tsx:107 | common.copied | 账号 ID 复制成功 |
| pages/settings/account.tsx:110 | common.copyFailed | 账号 ID 复制失败 |
二、Rust 后端返回错误
小米账号登录
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| frontapi/account.rs:270 | 原生小米账号登录窗口已在运行，请关闭后重试 | 登录窗口冲突 |
| frontapi/account.rs:317 | {context} 缺少小米账号 ID，拒绝保存不完整登录态 | 不完整账号保存 |
| frontapi/account.rs:478 | 拉起原生小米账号两步验证页面超时 | 2FA 超时 |
| frontapi/account.rs:505 | 无法拉起 iOS 原生小米账号两步验证页面 | iOS 2FA 启动失败 |
| frontapi/account.rs:514 | 原生小米账号两步验证失败: | 2FA 失败 |
| frontapi/account.rs:552 | 两步验证已完成，但原生验证页未返回 account.xiaomi.com 的 cookie | 2FA 缺少 cookie |
| frontapi/account.rs:605 | 等待小米账号两步验证超时 | 2FA 等待超时 |
| frontapi/account.rs:718 | 两步验证已完成，但未能读取到 account.xiaomi.com 的 cookie | 2FA cookie 读取失败 |
| frontapi/account.rs:809 | 小米账号两步验证窗口已被关闭 | 2FA 窗口被关闭 |
| frontapi/account.rs:820 | 小米账号两步验证窗口状态丢失 | 2FA 窗口状态丢失 |
| frontapi/account.rs:824 | 等待小米账号两步验证超时 | 2FA 等待超时 |
| frontapi/account.rs:1746 | 小米账号登录失败：用户名或密码错误 | 凭据错误 |
| frontapi/account.rs:2034 | 小米账号登录失败： | 通用登录失败 |
| frontapi/account.rs:2094 | 登录失败：用户名或密码错误 | API 错误 70016 |
| frontapi/account.rs:2131 | 小米账号登录过期，请重新登录 | 会话过期 |
| frontapi/account.rs:2307 | Xiaomi device id is required | 固件检查验证 |
| frontapi/account.rs:2310 | Xiaomi device model is required | 固件检查验证 |
| frontapi/account.rs:2313 | Current firmware version is required | 固件检查验证 |
vivo 账号登录
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| frontapi/account.rs:291 | 原生 vivo 登录窗口已在运行，请关闭后重试 | 登录窗口冲突 |
| frontapi/account.rs:939 | vivo 登录已完成，但未能从页面或 cookie 中取得 openid | 缺少 openid |
| frontapi/account.rs:1162 | vivo 登录窗口已被关闭 | 登录窗口被关闭 |
| frontapi/account.rs:1172 | vivo 登录窗口状态丢失 | 登录窗口状态丢失 |
| frontapi/account.rs:1176 | 等待 vivo 登录超时 | 登录等待超时 |
| frontapi/account.rs:1268 | 拉起原生 vivo 登录页面超时 | 登录超时 |
| frontapi/account.rs:1294 | 无法拉起 iOS 原生 vivo 登录页面 | iOS 登录启动失败 |
| frontapi/account.rs:1315 | 原生 vivo 登录失败: | 登录失败 |
| frontapi/account.rs:1328 | 等待 vivo 登录超时 | 登录等待超时 |
| frontapi/account.rs:2371 | vivo device id is required | OTA 验证 |
| frontapi/account.rs:2374 | vivo OTA device model is required | OTA 验证 |
| frontapi/account.rs:2377 | Current firmware version is required | OTA 验证 |
通用账号
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| frontapi/account.rs:2156 | provider not found | 账号提供商查找失败 |
三、WASM / 逻辑层抛错
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| logic/xiaomi.ts:182 | 小米 API 相关错误 | 小米 API 调用失败 |
| logic/xiaomi.ts:245 | 小米 API 相关错误 | 小米 API 调用失败 |
| pages/settings/account.tsx:95 | clipboard unavailable | 剪贴板不可用 |
四、其他排查建议
| 报错 | 建议操作 |
|---|---|
| 用户名或密码错误 | 确认账号密码正确，注意大小写 |
| 小米账号登录窗口已在运行 | 关闭已有的登录窗口后重试 |
| 等待两步验证超时 | 检查网络连接，或尝试重新登录 |
| 原生验证页未返回 cookie | 完成 2FA 后确保页面正常跳转，或尝试重新登录 |
| settings.account.bandBbsSyncNetworkError | 检查网络连接，稍后自动重试 |
| 账号已被封禁 | 联系 AstroBox 客服了解封禁原因 |
| 你的社交功能已被限制 | 等待限制解除时间到期 |
| account.sessionExpired | 重新登录 AstroBox 账号 |
| Current firmware version is required | 先连接设备以获取当前固件版本 |
音乐管理报错
音乐导入、歌单管理过程中可能出现的报错、解决方案及说明
本文档汇总 AstroBox 在音乐导入、歌单创建/编辑/删除等流程中可能向用户展示的报错信息。常见报错与解决方案已置顶，完整清单见文末。
常见报错与解决方案
device.connect.noDevice（无已连接设备）
报错原文
device.connect.noDevice触发场景：音乐导入/上传开始时没有已连接的设备，任务卡片也会显示此错误。
解决方案：先连接设备再导入音乐。
源码位置：logic/queue/musichelper.ts:120
Music file is empty
报错原文
Music file is empty触发场景：上传的音乐文件内容为空（0 字节或读取失败）。
解决方案：确认音乐文件未损坏且大小正常，重新选择文件。
源码位置：frontapi/device/music.rs:271
Songlist operation failed（歌单操作失败）
报错原文
Songlist operation failed: {code:?}触发场景：设备端歌单操作（添加/移除歌曲等）返回失败状态码。
解决方案：检查设备连接状态，或稍后重试；如反复失败重启设备。
源码位置：frontapi/device/music.rs:309 / frontapi/device/music.rs:453
Device rejected the song removal request
报错原文
bash
Device rejected the song removal request触发场景：设备拒绝了歌曲移除请求（常见于存储异常或设备忙）。
解决方案：检查设备存储空间，或重启设备后重试。
源码位置：frontapi/device/music.rs:252
device.music.songlistLimitReached（歌单数量达上限）
报错原文
device.music.songlistLimitReached触发场景：创建歌单时数量已达到设备上限。
解决方案：删除不必要的歌单后再创建。
源码位置：pages/device/music.tsx:297
完整报错清单
一、Toast 弹窗报错
音乐导入
| 触发位置 | 消息 Key | 说明 |
|---|---|---|
| pages/device/music.tsx:120 | device.music.importQueued | 音乐导入入队成功（count > 0） |
| pages/device/music.tsx:123 | error.message / String(error) | 音乐导入失败 |
| pages/device/music.tsx:277 | device.music.importQueued | MusicContent 导入入队成功 |
| pages/device/music.tsx:280 | error.message / String(error) | MusicContent 导入失败 |
歌单管理
| 触发位置 | 消息 Key | 说明 |
|---|---|---|
| pages/device/music.tsx:306 | device.music.songlistCreated | 歌单创建成功 |
| pages/device/music.tsx:322 | device.music.songlistRenamed | 歌单重命名成功 |
| pages/device/music.tsx:338 | device.music.songlistDeleted | 歌单删除成功 |
| pages/device/music.tsx:357 | device.music.songlistUpdated | 歌曲加入歌单成功 |
| pages/device/music.tsx:378 | device.music.songRemovedFromSonglist | 歌曲从歌单移除成功 |
| pages/device/music.tsx:402 | device.music.songDeleted | 歌曲从设备删除成功 |
歌单排序与验证
| 触发位置 | 消息 Key | 说明 |
|---|---|---|
| pages/device/music.tsx:427 | device.music.sortSaved | 歌单排序保存成功 |
| pages/device/music.tsx:431 | error.message / String(error) | 歌单排序保存失败 |
| pages/device/music.tsx:925 | device.music.songlistNameRequired | 歌单名为空 |
| pages/device/music.tsx:931 | error.message / String(error) | 创建/重命名歌单失败 |
| pages/device/music.tsx:1005 | device.music.selectSongsRequired | 未选择歌曲 |
| pages/device/music.tsx:1011 | error.message / String(error) | 歌曲选择提交失败 |
其他错误
| 触发位置 | 消息 | 说明 |
|---|---|---|
| pages/device/music.tsx:220 | error.message / String(error) | 加载歌单成员失败 |
| pages/device/music.tsx:297 | device.music.songlistLimitReached | 歌单数量达到上限（throw 后被 catch） |
二、队列内嵌报错（progressDesc）
taskList.ts 捕获音乐上传 action 异常后写入任务卡片：
| 来源 | 典型错误消息 | 触发场景 |
|---|---|---|
| musichelper.ts | device.connect.noDevice | 音乐上传开始时无设备 |
| musichelper.ts | device.music.queuePreparing | 准备上传中 |
| musichelper.ts | device.music.queueUploading + 进度 | 上传进行中 |
| musichelper.ts | device.music.queueDone | 上传完成 |
| musichelper.ts | device.music.queueDuplicated | 歌曲已存在 |
三、Rust 后端返回错误
音乐存储查询
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| frontapi/device/music.rs:85 | Device storage response not received: | 音乐存储查询失败 |
| frontapi/device/music.rs:91 | Device storage request timed out | 音乐存储查询超时 |
歌曲操作
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| frontapi/device/music.rs:252 | Device rejected the song removal request | 歌曲移除被拒绝 |
| frontapi/device/music.rs:271 | Music file is empty | 音乐文件为空 |
| frontapi/device/music.rs:309 | Songlist operation failed: | 歌单操作失败 |
| frontapi/device/music.rs:392 | 歌曲摘要错误 | |
| frontapi/device/music.rs:393 | Song summary response not received: | 歌曲摘要响应未收到 |
| frontapi/device/music.rs:394 | Song summary request timed out | 歌曲摘要请求超时 |
| frontapi/device/music.rs:413 | 传播内部 err | 歌曲添加失败 |
| frontapi/device/music.rs:453 | Songlist operation failed: | 歌单操作失败 |
| frontapi/device/music.rs:545 | Music file data is missing | 音乐数据缺失 |
标签响应
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| frontapi/device/music.rs:578 | 标签响应错误 | |
| frontapi/device/music.rs:581 | {label} response not received: | 标签响应未收到 |
| frontapi/device/music.rs:585 | {label} request timed out | 标签请求超时 |
四、WASM / 逻辑层抛错
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| logic/queue/musichelper.ts:120 | device.connect.noDevice | 音乐上传时无设备 |
| ipc/wasmBridge.ts:99 | thirdpartyapp_install_by_url is not implemented for wasm runtime | WASM 不支持 URL 安装 |
| ipc/wasmBridge.ts:101 | thirdpartyapp_stop_install_by_url is not implemented for wasm runtime | WASM 不支持停止 URL 安装 |
| ipc/wasmBridge.ts:103 | thirdpartyapp_cancel_install_by_url is not implemented for wasm runtime | WASM 不支持取消 URL 安装 |
五、其他排查建议
| 报错 | 建议操作 |
|---|---|
| device.music.songlistNameRequired | 确保输入了歌单名称 |
| device.music.selectSongsRequired | 至少选择一首歌曲 |
| Music file data is missing | 确认文件已成功选择，重新选择文件 |
表盘编辑报错
表盘编辑、应用、预览过程中可能出现的报错、解决方案及说明
本文档汇总 AstroBox 在表盘编辑、自定义文本、字体选择、应用等流程中可能向用户展示的报错信息。常见报错与解决方案已置顶，完整清单见文末。
常见报错与解决方案
queue.watchfaceIdConflict（表盘 ID 冲突）
报错原文
queue.watchfaceIdConflict触发场景：安装表盘时检测到 downgrade 冲突（设备上已有同 ID 或更高版本的表盘）。toast 会附带「覆盖安装」按钮，也可在设置中开启「强制安装表盘」。
解决方案：确认是否覆盖安装，或更换不同 ID 的表盘。
源码位置：logic/queue/installhelper.ts:169（前端）；设备端对应 install prepare failed with status: Downgrade（modules/core/src/device/xiaomi/components/install.rs:207）
device.watchfaces.edit.text.invalid（文本验证失败）
报错原文
device.watchfaces.edit.text.invalid触发场景：应用表盘编辑时自定义文本内容不符合表盘规范。
解决方案：检查文本内容是否符合表盘规范（长度、字符集等）。
源码位置：pages/device/watchfaceEdit.tsx:1071
device.watchfaces.edit.text.fontMissing（字体缺失/多选）
报错原文
device.watchfaces.edit.text.fontMissing触发场景：文本字面量未选择字体，或同时选择了多种字体。
解决方案：确保只选择了一种字体，或选择有效字体。
源码位置：pages/device/watchfaceEdit.tsx:1113
device.watchfaces.edit.text.fontReadFailed（字体读取失败）
报错原文
device.watchfaces.edit.text.fontReadFailed触发场景：读取本地字体文件失败（文件损坏或权限问题）。
解决方案：确认字体文件未损坏，尝试更换字体文件。
源码位置：pages/device/watchfaceEdit.tsx:1230
device.watchfaces.edit.applyFailed（表盘应用失败）
报错原文
device.watchfaces.edit.applyFailed触发场景：表盘编辑应用（推送）失败，常见于设备断联或表盘文件不完整。
解决方案：检查设备连接状态，确认表盘文件完整后重试。
源码位置：pages/device/watchfaceEdit.tsx:1147
hb_subset_or_fail failed（字体子集化失败）
报错原文
hb_subset_or_fail failed (font unsupported?)触发场景：HarfBuzz 对所选字体做子集化失败，字体格式不受支持。
解决方案：字体文件可能不兼容，尝试使用标准 TTF/OTF 字体。
源码位置：logic/fontSubset.ts:92
完整报错清单
一、Toast 弹窗报错
表盘编辑页面
| 触发位置 | 消息 Key | 说明 |
|---|---|---|
| pages/device/watchfaceEdit.tsx:1071 | device.watchfaces.edit.text.invalid | 文本验证失败 |
| pages/device/watchfaceEdit.tsx:1113 | device.watchfaces.edit.text.fontMissing | 文本字面量多字体或无字体 |
| pages/device/watchfaceEdit.tsx:1143 | device.watchfaces.edit.applied | 表盘编辑应用成功 |
| pages/device/watchfaceEdit.tsx:1147 | device.watchfaces.edit.applyFailed | 表盘编辑应用失败 |
| pages/device/watchfaceEdit.tsx:1230 | device.watchfaces.edit.text.fontReadFailed | 字体文件读取失败 |
二、Rust 后端返回错误
表盘列表与应用
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| frontapi/device/watchface.rs:10 | format_anyhow(&err) | 获取表盘列表失败 |
| frontapi/device/watchface.rs:19 | format_anyhow(&err) | 应用表盘失败 |
| frontapi/device/watchface.rs:27 | format_anyhow(&err) | 反编译表盘失败 |
表盘编辑核心
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| watchface_edit/commands.rs:126 | err.to_string() | 表盘归档解析错误 |
| watchface_edit/commands.rs:197 | format!("{err:#}") | 表盘反编译错误 |
| watchface_edit/commands.rs:245 | join parse task: | 异步解析 join 错误 |
| watchface_edit/commands.rs:265 | format!("{err:#}") | 表盘应用错误 |
三、队列内嵌报错（progressDesc）
表盘安装任务若失败，taskList.ts 会将错误写入 progressDesc：
queue.watchfaceIdConflict — 表盘 ID 冲突/降级冲突 resource.unknown.type — 文件类型未知 device.connect.noDevice — 安装时无设备连接
四、WASM / 逻辑层抛错
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| logic/fontSubset.ts:67 | subsetFont: empty text | 字体子集文本为空 |
| logic/fontSubset.ts:86 | hb_subset_input_create_or_fail failed | HarfBuzz 输入创建失败 |
| logic/fontSubset.ts:92 | hb_subset_or_fail failed (font unsupported?) | HarfBuzz 子集失败 |
| logic/fontSubset.ts:97 | subset produced empty font | 字体子集结果为空 |
五、其他排查建议
| 报错 | 建议操作 |
|---|---|
| subset produced empty font | 确认文本内容不为空，且字体支持对应字符 |
插件系统报错
插件安装、启用、禁用、卸载过程中可能出现的报错、解决方案及说明
本文档汇总 AstroBox 在插件安装、管理、运行等流程中可能向用户展示的报错信息。常见报错与解决方案已置顶，完整清单见文末。
常见报错与解决方案
plugin.install.unsupported（插件安装不受支持）
报错原文
plugin.install.unsupported触发场景：在非 Tauri 环境（Web/WASM）尝试安装插件，或 ABP 文件以 Web File 对象传入。
解决方案：插件安装仅支持 Tauri 桌面端，Web/WASM 不支持。
源码位置：logic/queue/installhelper.ts:555 / logic/queue/pluginhelper.ts:67
plugin.install.failed: store base empty（插件存储为空）
报错原文
plugin.install.failed: store base empty触发场景：插件存储基础目录为空，无法写入插件。
解决方案：检查插件存储目录权限，或重启 AstroBox。
源码位置：frontapi/plugsys.rs:284
Plugin '{name}' is disabled（插件已禁用）
报错原文
Plugin '{name}' is disabled触发场景：尝试启动已禁用的插件，或打开已禁用插件的 UI。
解决方案：先启用插件再执行操作。
源码位置：frontapi/plugsys.rs:566 / frontapi/plugsys.rs:602
Plugin '{name}' is not loaded（插件未加载）
报错原文
Plugin '{name}' is not loaded触发场景：插件未正确加载（安装不完整或启动失败）。
解决方案：检查插件是否正确安装，尝试重新安装。
源码位置：frontapi/plugsys.rs:577 / frontapi/plugsys.rs:613
Plugin '{name}' is not ready（插件未就绪）
报错原文
Plugin '{name}' is not ready触发场景：插件初始化未完成即被调用 RPC 或查询状态。
解决方案：等待插件初始化完成，或重启应用。
源码位置：frontapi/plugsys.rs:644 / frontapi/plugsys.rs:673
aggregate index.json does not contain valid plugins（插件市场索引无效）
报错原文
aggregate index.json does not contain valid plugins触发场景：插件市场聚合索引文件无效，无法列出可用插件。
解决方案：插件市场源配置错误，检查源地址。
源码位置：logic/pluginMarket.ts:308
完整报错清单
、Toast 弹窗报错
插件安装
| 触发位置 | 消息 Key | 说明 |
|---|---|---|
| queue.tsx:146 | plugin.install.unsupported | 非 Tauri 运行时安装插件 |
| pages/plugin/storeDetail.tsx:83 | plugin.install.unsupported | 非 Tauri 环境安装插件 |
| logic/queue/pluginhelper.ts:91 | plugin.install.success | 插件下载并安装成功 |
插件操作
| 触发位置 | 消息 | 说明 |
|---|---|---|
| pages/plugin/detail.tsx:344 | plugin.action.enableFailed | 启用插件失败 |
| pages/plugin/detail.tsx:350 | plugin.action.disableFailed | 禁用插件失败 |
| pages/plugin/detail.tsx:356 | err.message / plugin.action.updateFailed | 插件状态切换失败 |
| pages/plugin/detail.tsx:375 | plugin.action.uninstallFailed | 卸载插件失败 |
| pages/plugin/detail.tsx:388 | err.message / plugin.action.uninstallFailed | 卸载插件失败 |
二、队列内嵌报错（progressDesc）
taskList.ts 捕获插件任务异常后写入任务卡片：
| 来源 | 典型错误消息 | 触发场景 |
|---|---|---|
| pluginhelper.ts | plugin.install.unsupported | 插件安装不支持 |
| pluginhelper.ts | plugin.install.failed: store base empty | 插件存储基础为空 |
三、Rust 后端返回错误
插件系统核心
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| frontapi/plugsys.rs:224 | invalid path component in {relative_path} | 插件路径验证 |
| frontapi/plugsys.rs:284 | store base is empty | 插件存储验证 |
| frontapi/plugsys.rs:325 | manifest entry is empty | 插件清单验证 |
| frontapi/plugsys.rs:474 | Failed to remove plugin directory: | 插件目录移除 |
| frontapi/plugsys.rs:492 | Invalid folder name: path traversal detected | 路径遍历检测 |
| frontapi/plugsys.rs:517 | Failed to remove plugin directory: | 插件目录移除 |
| frontapi/plugsys.rs:566 | Plugin '{name}' is disabled | 插件启动验证 |
| frontapi/plugsys.rs:570 | err.to_string() | 插件启动失败 |
| frontapi/plugsys.rs:577 | Plugin '{name}' is not loaded | 插件未加载 |
| frontapi/plugsys.rs:602 | Plugin '{name}' is disabled | 插件 UI 打开验证 |
| frontapi/plugsys.rs:606 | err.to_string() | 插件 UI 打开失败 |
| frontapi/plugsys.rs:613 | Plugin '{name}' is not loaded | 插件 UI 打开验证 |
| frontapi/plugsys.rs:644 | Plugin '{name}' is not ready | 插件 RPC 验证 |
| frontapi/plugsys.rs:673 | Plugin '{name}' is not ready | 插件状态验证 |
插件平台 Stub
| 插件 | 错误消息 | 触发条件 |
|---|---|---|
| iap/src/error.rs IAP | is not supported on this platform | |
| iap/src/stub.rs | Err(Error::UnsupportedPlatform) | 不支持平台的所有 IAP 操作 |
| inappbrowser/src/stub.rs | Err(Error::UnsupportedPlatform) | 不支持平台的所有浏览器操作 |
| cloud-push/src/stub.rs | cloud push is not supported on this platform | 云推送不支持 |
| ive-activity/src/error.rs | Error::Io(...) / Error::PluginInvoke(...) | 实时活动序列化错误 |
四、WASM / 逻辑层抛错
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| logic/queue/pluginhelper.ts:67 | plugin.install.unsupported | 插件安装不支持 |
| logic/queue/pluginhelper.ts:70 | plugin.install.failed: store base empty | 插件存储基础为空 |
| logic/pluginMarket.ts:308 | aggregate index.json does not contain valid plugins | 插件市场聚合索引无效 |
| ipc/wasmBridge.ts:99 | thirdpartyapp_install_by_url is not implemented for wasm runtime | WASM 不支持 |
| ipc/wasmBridge.ts:101 | thirdpartyapp_stop_install_by_url is not implemented for wasm runtime | WASM 不支持 |
| ipc/wasmBridge.ts:103 | thirdpartyapp_cancel_install_by_url is not implemented for wasm runtime | WASM 不支持 |
五、其他排查建议
| 报错 | 建议操作 |
|---|---|
| manifest entry is empty | 插件包可能损坏，尝试重新下载安装 |
| Invalid folder name: path traversal detected | 插件包包含非法路径，联系插件作者 |
| IAP is not supported on this platform | 内购功能在当前平台不可用 |
设置与工具报错
设置页面、高级工具、文件选择器等可能出现的报错、解决方案及说明
本文档汇总 AstroBox 在设置页面、高级工具、文件选择器、缓存清理、传输诊断等流程中可能向用户展示的报错信息。常见报错与解决方案已置顶，完整清单见文末。
常见报错与解决方案
settings.general.runtimeCache.failed（运行时缓存清理失败） 报错原文
settings.general.runtimeCache.failed + <错误消息> 触发场景：清理运行时缓存失败（failed to clear cache: {failures}，常见于文件被占用或权限不足）。
解决方案：检查存储权限，关闭可能占用缓存文件的窗口，或手动清理缓存目录。
源码位置：pages/settings/general.tsx:288（前端）；frontapi/app.rs:334（后端）
settings.network.doh.invalidCustomUrl（自定义 DOH 地址无效） 报错原文
settings.network.doh.invalidCustomUrl 触发场景：自定义 DOH URL 为空或格式无效，或 DOH 配置写入失败。
解决方案：确认 DOH URL 格式正确，以 https:// 开头。
源码位置：pages/settings/networkShared.tsx:522/549/577/590；逻辑层 logic/networkSettings.ts:186（invalid-custom-doh-url）
settings.network.speedTest.failed（测速失败） 报错原文
settings.network.speedTest.failed 触发场景：所有测速探针均超时或失败。
解决方案：检查网络连接，或切换其他网络后重试。
源码位置：pages/settings/networkShared.tsx:638
settings.extratools.fetchLogs 失败（获取设备日志失败） 报错原文
error.message / String(error) 触发场景：获取设备日志失败（常见触发链：failed to decode reverse MASS packet / failed to assemble reverse MASS payload: block N was not found!，设备侧丢包）。
解决方案：检查设备连接状态；如为 MASS 丢包，拉取前先重启设备、清理手表内存。
源码位置：pages/settings/extratools.tsx:1099；设备侧 modules/core/src/device/xiaomi/components/mass.rs:251、packet/mass.rs:215
settings.extratools.transportDiag 相关失败（传输诊断失败） 报错原文
message（归一化错误） 触发场景：传输抓包开始/停止、冒烟测试失败（常见于设备断联或蓝牙异常）。
解决方案：确认设备已连接，检查蓝牙状态后重试。
源码位置：pages/settings/extratools.tsx:948/975/1010；后端 frontapi/device/transport_diag.rs
filePicker.openFailed（文件选择器打开失败） 报错原文
filePicker.openFailed / filePicker.openFailed: <detail> 触发场景：Tauri 或 Web 文件选择器调用异常，或移动端选择了不支持的操作（如移动端文件夹选择）。
解决方案：确认系统文件选择权限；移动端不支持文件夹选择，改用文件选择。
源码位置：logic/filePicker.ts:144；后端 frontapi/file_picker.rs:152/453
分享相关失败（sharing is not supported 等） 报错原文
sharing is not supported on this platform / 当前系统不支持原生文件分享 / 拉起系统分享超时 触发场景：当前平台不支持系统分享，或分享超时/失败。
解决方案：当前平台不支持系统分享功能；如为超时可稍后重试。
源码位置：frontapi/app.rs:543/727/740/769/779
No recordings selected（未选择录音） 报错原文
No recordings selected 触发场景：导出录音时未选择任何录音。
解决方案：先选择要导出的录音。
源码位置：frontapi/device/record.rs:161
Recording {name} cannot be exported（录音格式不支持导出） 报错原文
Recording {name} cannot be exported 触发场景：录音格式不支持导出。
解决方案：该录音格式不支持导出，尝试其他方式。
源码位置：frontapi/device/record.rs:511
Failed to open debugwindow（调试窗口打开失败） 报错原文
Failed to open debugwindow：<message> 触发场景：打开调试窗口失败（注意：这是项目中唯一一处使用原生 alert() 展示的报错，非 toast）。
解决方案：检查窗口管理器权限，或重启应用。
源码位置：pages/settings/extratools.tsx:644
完整报错清单 一、Toast 弹窗报错 通用设置
| 触发位置 | 消息 Key | 说明 |
|---|---|---|
| pages/settings/general.tsx:281 | settings.general.runtimeCache.success + 清理大小 | 运行时缓存清理成功 |
| pages/settings/general.tsx:288 | settings.general.runtimeCache.failed + 错误消息 | 运行时缓存清理失败 |
| 网络设置 | ||
| 触发位置 | 消息 Key | 说明 |
| --- | --- | --- |
| pages/settings/networkShared.tsx:495 | settings.network.proMirrorLocked | 非 Pro 用户选择 Pro CDN |
| pages/settings/networkShared.tsx:522 | settings.network.doh.invalidCustomUrl | DOH 配置写入失败 |
| pages/settings/networkShared.tsx:549 | settings.network.doh.invalidCustomUrl | 自定义 DOH URL 无效 |
| pages/settings/networkShared.tsx:577 | settings.network.doh.invalidCustomUrl | 选择自定义 DOH 时 URL 无效 |
| pages/settings/networkShared.tsx:590 | settings.network.doh.invalidCustomUrl | 提交自定义 DOH URL 为空/无效 |
| pages/settings/networkShared.tsx:636 | settings.network.speedTest.completed | 至少一个测速探针成功 |
| pages/settings/networkShared.tsx:638 | settings.network.speedTest.failed | 所有探针超时/失败 |
| pages/settings/networkShared.tsx:726 | settings.network.speedTest.noAvailableResult | 无成功测速结果 |
| pages/settings/networkShared.tsx:734 | settings.network.speedTest.applied | 最佳 CDN/源已应用 |
| 通知设置 | ||
| 触发位置 | 消息 Key | 说明 |
| --- | --- | --- |
| pages/settings/notifications.tsx:108 | settings.notifications.remotePush.updateFailed + error | 推送通道更新失败 |
| pages/settings/notifications.tsx:123 | settings.notifications.remotePush.enableSuccess | 推送注册成功 |
| pages/settings/notifications.tsx:126 | settings.notifications.remotePush.permissionDenied | 推送权限被拒绝 |
| pages/settings/notifications.tsx:129 | settings.notifications.remotePush.enableFailed + result | 推送注册其他失败 |
| pages/settings/notifications.tsx:136 | settings.notifications.remotePush.disableSuccess | 推送注销成功 |
| pages/settings/notifications.tsx:139 | settings.notifications.remotePush.enableFailed + error | 推送注销失败 |
| 高级工具 | ||
| 触发位置 | 消息 Key | 说明 |
| --- | --- | --- |
| pages/settings/extratools.tsx:684 | settings.extratools.logsShareFailed + message | 日志归档分享失败 |
| pages/settings/extratools.tsx:695 | device.noDevice | 打开设备信息时无设备地址 |
| pages/settings/extratools.tsx:899 | common.copied | 设备信息复制成功 |
| pages/settings/extratools.tsx:902 | common.copyFailed | 设备信息复制失败 |
| pages/settings/extratools.tsx:934 | device.noDevice | 开始传输抓包时无连接设备 |
| pages/settings/extratools.tsx:944 | settings.extratools.transportDiag.captureStarted | 传输抓包已开始 |
| pages/settings/extratools.tsx:948 | message（归一化错误） | 传输抓包启动失败 |
| pages/settings/extratools.tsx:956 | device.noDevice | 停止传输抓包时无设备地址 |
| pages/settings/extratools.tsx:971 | settings.extratools.transportDiag.captureStopped | 传输抓包已停止 |
| pages/settings/extratools.tsx:975 | message（归一化错误） | 传输抓包停止失败 |
| pages/settings/extratools.tsx:983 | device.noDevice | 运行传输冒烟测试时无连接设备 |
| pages/settings/extratools.tsx:1006 | settings.extratools.transportDiag.smokeFinished | 传输冒烟测试完成 |
| pages/settings/extratools.tsx:1010 | message（归一化错误） | 传输冒烟测试失败 |
| pages/settings/extratools.tsx:1022 | common.copied | 传输报告复制成功 |
| pages/settings/extratools.tsx:1025 | common.copyFailed | 传输报告复制失败 |
| pages/settings/extratools.tsx:1031 | settings.extratools.watchfacePreview.nativeOnly | 非 Tauri 运行时打开表盘预览 |
| pages/settings/extratools.tsx:1058 | device.noDevice | 获取设备日志时无连接设备 |
| pages/settings/extratools.tsx:1093 | settings.extratools.fetchLogs + 保存路径 | 桌面端日志获取成功 |
| pages/settings/extratools.tsx:1099 | error.message / String(error) | 日志获取失败 |
| pages/settings/extratools.tsx:1267 | device.noDevice | 传输诊断弹窗刷新时无连接设备 |
| 原生 alert（唯一一处） | ||
| 触发位置 | 消息 | 说明 |
| --- | --- | --- |
| pages/settings/extratools.tsx:644 | Failed to open debugwindow：$ | debug window 打开失败（阻断式弹窗） |
| 录音导出 | ||
| 触发位置 | 消息 Key | 说明 |
| --- | --- | --- |
| pages/device/record.tsx:230 | device.record.exportSuccessTo + 文件数 + 目录 | 非移动端导出成功 |
| pages/device/record.tsx:242 | error.message / String(error) | 导出失败（非分享取消） |
| 二、Rust 后端返回错误 | ||
| 文件选择器 | ||
| 位置 | 错误消息 | 触发条件 |
| --- | --- | --- |
| frontapi/file_picker.rs:152 | folder picker is not implemented on mobile | 移动端文件夹选择 |
| frontapi/file_picker.rs:211 | message.to_string() | 桌面文件选择器错误 |
| frontapi/file_picker.rs:222 | message.to_string() | 桌面文件夹选择器错误 |
| frontapi/file_picker.rs:338 | error string | macOS 文件选择器错误 |
| frontapi/file_picker.rs:360 | message | Android 文件选择器错误 |
| frontapi/file_picker.rs:377 | message | iOS 文件选择器错误 |
| frontapi/file_picker.rs:453 | folder picker is not implemented on iOS | iOS 文件夹选择 |
| frontapi/file_picker.rs:496 | failed to launch iOS native file picker | iOS 文件选择器启动失败 |
| frontapi/file_picker.rs:532 | error | iOS 文件选择器结果错误 |
| 网络/HTTP 代理 | ||
| 位置 | 错误消息 | 触发条件 |
| --- | --- | --- |
| frontapi/network.rs:226 | invalid http method: method is empty | HTTP 方法为空 |
| frontapi/network.rs:281 | invalid http method: | HTTP 方法不支持 |
| frontapi/network.rs:392 | body_text and body_json are mutually exclusive | 请求体验证 |
| 分享与缓存 | ||
| 位置 | 错误消息 | 触发条件 |
| --- | --- | --- |
| frontapi/app.rs:543 | sharing is not supported on this platform | 原生文件分享不支持 |
| frontapi/app.rs:624 | failed to allocate a unique share cache file path | 分享缓存路径分配失败 |
| frontapi/app.rs:727 | Android 原生分享启动失败 | Android 分享启动失败 |
| frontapi/app.rs:740 | 拉起系统分享超时 | 分享超时 |
| frontapi/app.rs:769 | 无法拉起系统分享 | 分享失败 |
| frontapi/app.rs:779 | 当前系统不支持原生文件分享 | 平台不支持分享 |
| frontapi/app.rs:334 | failed to clear cache: | 运行时缓存清理失败 |
| 录音导出 | ||
| 位置 | 错误消息 | 触发条件 |
| --- | --- | --- |
| frontapi/device/record.rs:114 | 录音导出错误 | |
| frontapi/device/record.rs:118 | Record export response not received: | 录音导出响应未收到 |
| frontapi/device/record.rs:122 | Record export request timed out | 录音导出请求超时 |
| frontapi/device/record.rs:161 | No recordings selected | 未选择录音 |
| frontapi/device/record.rs:281 | No recording export task completed successfully | 所有导出失败 |
| frontapi/device/record.rs:296 | 主要导出错误 | |
| frontapi/device/record.rs:331 | 录音获取错误 | |
| frontapi/device/record.rs:334 | {label} response not received: | 录音获取响应未收到 |
| frontapi/device/record.rs:338 | {label} request timed out | 录音获取超时 |
| frontapi/device/record.rs:477 | 分享导出错误 | |
| frontapi/device/record.rs:483 | {label} response not received: | 分享响应未收到 |
| frontapi/device/record.rs:489 | Timed out while exporting recordings for sharing | 分享导出超时 |
| frontapi/device/record.rs:511 | Recording {name} cannot be exported | 不支持的录音格式 |
| 三、WASM / 逻辑层抛错 | ||
| 位置 | 错误消息 | 触发条件 |
| --- | --- | --- |
| logic/filePicker.ts:144 | filePicker.openFailed: ${detail} / filePicker.openFailed | 文件选择器打开失败 |
| logic/share.ts:59 | settings.extratools.logsShareUnsupported | 日志分享不支持 |
| logic/share.ts:76 | settings.extratools.logsShareUnsupported | 日志分享不支持 |
| logic/networkSettings.ts:186 | invalid-custom-doh-url | 自定义 DOH URL 无效 |
| logic/networkHttp.ts:395 | persistTempDownload is only available in Tauri runtime | 非 Tauri 调用 |
| logic/networkHttp.ts:407 | deleteTempDownload is only available in Tauri runtime | 非 Tauri 调用 |
| pages/settings/extratools.tsx:351 | clipboard unavailable | 剪贴板不可用 |
| 四、其他排查建议 | ||
| 报错 | 建议操作 | |
| --- | --- | |
| device.noDevice | 先连接设备再执行相关操作 | |
| settings.network.speedTest.noAvailableResult | 检查网络连接，或切换其他网络后重试 | |
| settings.notifications.remotePush.permissionDenied | 在系统设置中开启推送权限 | |
| settings.extratools.watchfacePreview.nativeOnly | 表盘预览仅支持 Tauri 桌面端 | |
| clipboard unavailable | 检查浏览器/系统剪贴板权限 |
系统与框架级报错
系统框架、热更新、版本检查、底层通信等可能出现的报错、解决方案及说明
本文档汇总 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（深度链接无效）
报错原文
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:384 | message（ACCOUNT_SESSION_EXPIRED_EVENT payload，或回退到 account.sessionExpired） | 账号会话过期事件 |
| App.tsx:235 | translate(messageKey)（网络账号源自动切换提示） | 启动时自动切换账号源 |
关于页面 - 更新检查
| 触发位置 | 消息 Key | 说明 |
|---|---|---|
| pages/settings/about/index.tsx:614 | update.toast.noUpdate | 无可用更新 |
| pages/settings/about/index.tsx:618 | update.toast.checkFailed | 更新检查失败 |
赞助计划 - IAP
| 触发位置 | 消息 Key | 说明 |
|---|---|---|
| pages/settings/sponsorPlan.tsx:713 | settings.sponsorPlan.trialLoginRequired | 试用领取未登录 |
| pages/settings/sponsorPlan.tsx:724 | settings.sponsorPlan.trialClaimed | Creator Pro 试用领取成功 |
| pages/settings/sponsorPlan.tsx:732 | settings.sponsorPlan.trialAlreadyUsed | 已使用过试用 |
| pages/settings/sponsorPlan.tsx:736 | settings.sponsorPlan.trialClaimFailed | 试用领取其他失败 |
| pages/settings/sponsorPlan.tsx:1273 | settings.sponsorPlan.iapTransferred | 订阅转移成功 |
| pages/settings/sponsorPlan.tsx:1276 | settings.sponsorPlan.iapTransferFailed | 订阅转移失败 |
| pages/settings/sponsorPlan.tsx:1286 | settings.sponsorPlan.trialLoginRequired | AppStore 购买未登录 |
| pages/settings/sponsorPlan.tsx:1308 | settings.sponsorPlan.iapPending | 购买挂起中 |
| pages/settings/sponsorPlan.tsx:1312 | settings.sponsorPlan.iapMissingTransaction | 响应中无交易记录 |
| pages/settings/sponsorPlan.tsx:1321 | settings.sponsorPlan.iapActivated / iapAlreadyActivated | 验证通过/已激活 |
| pages/settings/sponsorPlan.tsx:1333 | settings.sponsorPlan.iapRevoked / iapFailed | 验证终端失败 |
| pages/settings/sponsorPlan.tsx:1340 | settings.sponsorPlan.iapVerifyPendingRetry | 验证暂态重试 |
| pages/settings/sponsorPlan.tsx:1347 | settings.sponsorPlan.iapPurchaseFailed + error | StoreKit 购买失败 |
| pages/settings/sponsorPlan.tsx:1370 | settings.sponsorPlan.trialLoginRequired | 恢复购买未登录 |
| pages/settings/sponsorPlan.tsx:1388 | settings.sponsorPlan.iapRestoreDone | 恢复购买成功 |
| pages/settings/sponsorPlan.tsx:1394 | settings.sponsorPlan.iapFailed | 恢复购买暂态错误 |
| pages/settings/sponsorPlan.tsx:1396 | settings.sponsorPlan.iapRestoreEmpty | 恢复购买无授权 |
| pages/settings/sponsorPlan.tsx:1401 | settings.sponsorPlan.iapFailed | 恢复购买失败 |
| pages/settings/sponsorPlan.tsx:1426 | settings.sponsorPlan.iapActivated | 未完成交易自动授权 |
二、Rust 后端返回错误
App 生命周期/调试
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| frontapi/app.rs:118 | build.devUrl is required in debug desktop mode | 桌面调试模式缺少 devUrl |
| frontapi/app.rs:121 | build.devUrl has no valid host/port: | devUrl 解析失败 |
| frontapi/app.rs:162 | dev server {addr} is unavailable... | 开发服务器不可达 |
| frontapi/app.rs:209 | failed 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:89 | persist_device_version_snapshot 错误 | 版本快照保存失败 |
| frontapi/device/update.rs:121 | Device info response not received: | 设备信息获取失败 |
| frontapi/device/update.rs:158 | Watchface list response not received: | 表盘列表获取失败 |
| frontapi/device/update.rs:214-223 | ... response not received: | 更新检查查询失败 |
| frontapi/device/update.rs:243 | Failed to load device version snapshots: | 快照加载失败 |
| frontapi/device/update.rs:255 | Failed to store device version snapshots: | 快照存储失败 |
| frontapi/device/update.rs:326 | format_anyhow(&err) | 更新通用错误 |
设备同步
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| frontapi/device/sync.rs:63 | manual input missing | 手动同步验证失败 |
| frontapi/device/sync.rs:71 | NTP query failed ({server}): | NTP 同步失败 |
传输诊断
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| frontapi/device/transport_diag.rs | format_anyhow(&err) | 传输状态/BLE/SPP/清除诊断失败 |
核心错误格式化
| 位置 | 功能 | 说明 |
|---|---|---|
| modules/core/src/error.rs | format_anyhow(err: &anyhow::Error) -> String | 渲染完整 Caused by: 链和可选回溯，被多个 frontapi 命令消费 |
FrontBridge 通信层
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| modules/frontbridge/src/lib.rs:158 | frontend invoke {method} dropped without response | 前端调用 Rust 后 oneshot channel 被丢弃 |
| modules/frontbridge/src/lib.rs:164-167 | frontend invoke {method} failed: | 前端显式报告 success: false |
三、WASM / 逻辑层抛错
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| logic/appUpdate.ts:114 | Invalid version response format | 版本响应格式无效 |
| logic/stats/storage.ts:214 | Unable to collect legacy stats from localStorage: $ | 旧版统计数据收集失败 |
| backendHandlers.ts:220 | Invalid deeplink payload | 深度链接 payload 无效 |
| backendHandlers.ts:227 | Missing resource id or provider | 深度链接缺少资源 ID 或提供商 |
| backendHandlers.ts:238 | Missing plugin name | 深度链接缺少插件名 |
| backendHandlers.ts:243 | Unknown deeplink target | 未知深度链接目标 |
四、本地 API / ServerLink
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| local_api/handlers.rs:35 | unsupported sort: | 排序验证 |
| local_api/handlers.rs:81/130/179/249/643/676/709/744 | app is not ready | ServerLink 应用未就绪 |
五、其他排查建议
| 报错 | 建议操作 |
|---|---|
| settings.sponsorPlan.trialLoginRequired | 先登录 AstroBox 账号 |
| frontend invoke ... dropped without response | 检查应用是否被系统挂起，重启应用 |
| Failed to load device version snapshots | 检查存储权限，或重启应用 |
社区与社交功能报错
资源评论、评分、举报、收件箱等社交功能可能出现的报错、解决方案及说明
本文档汇总 AstroBox 在资源评论、评分、举报、收件箱、个人资料等社区社交功能中可能向用户展示的报错信息。常见报错与解决方案已置顶，完整清单见文末。
常见报错与解决方案
请先登录 AstroBox 账号 报错原文
请先登录 AstroBox 账号触发场景：未登录状态下尝试举报资源或打开收件箱。
解决方案：先登录账号再使用社交功能。
源码位置：components/report/ReportDialog.tsx:51 / components/inbox/InboxButton.tsx:232
你的社交功能已被限制，解除时间：...
报错原文
你的社交功能已被限制，解除时间：{expiresAt}。{error.message}触发场景：后端返回 social-banned 错误码，账号社交功能被临时限制。
解决方案：等待限制解除时间到期，或联系客服。
源码位置：logic/api/astrobox/request.ts:162
账号已被封禁：...
报错原文
账号已被封禁：{error.message}触发场景：后端返回 user-banned 错误码，账号被封禁，随后会自动登出。
解决方案：联系 AstroBox 客服了解封禁原因。
源码位置：logic/api/astrobox/request.ts:169
resource.comment.permissionHint（无评论权限）
报错原文
resource.comment.permissionHint触发场景：无评论权限时尝试打开回复对话框。
解决方案：确认账号已完成实名认证或满足评论条件。
源码位置：pages/resource/detail.tsx:373
profile.edit.board.proRequired（看板功能需 Pro）
报错原文
profile.edit.board.proRequired触发场景：非 Pro 用户尝试添加看板。
解决方案：升级至 Creator Pro 以使用看板功能。
源码位置：pages/profileEdit.tsx:240
profile.collections.queueDeviceUnknown（收藏集入队设备未知）
报错原文
profile.collections.queueDeviceUnknown触发场景：收藏集批量入队时无法解析设备 ID。
解决方案：先连接设备并确保设备被正确识别。
源码位置：pages/profile.tsx:321
OfficialV2 device map is not ready（设备映射未就绪）
报错原文
OfficialV2 device map is not ready触发场景：OfficialV2 设备映射未加载完成即发起操作。
解决方案：等待设备映射加载完成，或刷新页面。
源码位置：components/resource/detail/Hero.tsx:203
请填写举报说明
报错原文
请填写举报说明触发场景：提交举报时举报原因为空。
解决方案：填写举报原因后再提交。
源码位置：components/report/ReportDialog.tsx:55
完整报错清单
一、Toast 弹窗报错
资源评论
资源详情页
| 触发位置 | 消息 | 说明 |
|---|---|---|
| pages/resource/detail.tsx:146 | err.message ?? err | 资源详情获取失败 |
| pages/resource/detail.tsx:160 | err.message ?? err | AstroBox 资源信息获取失败 |
| pages/resource/detail.tsx:279 | commentError?.message ?? commentError | 评论列表获取失败 |
| pages/resource/detail.tsx:302 | err.message ?? err | get_image_palette 调用失败 |
| pages/resource/detail.tsx:373 | resource.comment.permissionHint | 无评论权限却尝试回复 |
| pages/resource/detail.tsx:407 | err?.message ?? err | 提交回复失败 |
| pages/resource/detail.tsx:431 | err?.message ?? err | 删除评论失败 |
| pages/resource/detail.tsx:456 | err?.message ?? err | 点赞/取消点赞失败 |
| pages/resource/detail.tsx:610 | err?.message ?? err | 发送顶层评论失败 |
评论详情页
| 触发位置 | 消息 | 说明 |
|---|---|---|
| pages/resource/commentDetail.tsx:106 | error?.message ?? error | 评论详情获取失败 |
| pages/resource/commentDetail.tsx:154 | err?.message ?? err | 提交回复失败 |
| pages/resource/commentDetail.tsx:183 | err?.message ?? err | 删除评论失败 |
| pages/resource/commentDetail.tsx:208 | err?.message ?? err | 点赞/取消点赞失败 |
评分
| 触发位置 | 消息 Key | 说明 |
|---|---|---|
| components/resource/detail/RatingCard.tsx:255 | resource.rating.submitSuccess | 评分提交成功 |
| components/resource/detail/RatingCard.tsx:261 | err?.message ?? err | 评分提交失败 |
举报
| 触发位置 | 消息 | 说明 |
|---|---|---|
| components/report/ReportDialog.tsx:51 | 请先登录 AstroBox 账号（硬编码） | 举报时未登录 |
| components/report/ReportDialog.tsx:55 | 请填写举报说明（硬编码） | 举报原因为空 |
| components/report/ReportDialog.tsx:71 | 举报已提交（硬编码） | 举报提交成功 |
| components/report/ReportDialog.tsx:76 | err.message / String(err) | 举报提交失败 |
收件箱
| 触发位置 | 消息 | 说明 |
|---|---|---|
| components/inbox/InboxButton.tsx:118 | inboxError.message / String(inboxError) | 收件箱获取失败 |
| components/inbox/InboxButton.tsx:141 | err.message / String(err) | 标记已读失败 |
| components/inbox/InboxButton.tsx:174 | 已全部标记为已读（硬编码） | 全部标记已读成功 |
| components/inbox/InboxButton.tsx:176 | err.message / String(err) | 全部标记已读失败 |
| components/inbox/InboxButton.tsx:193 | err.message / String(err) | 删除消息失败 |
| components/inbox/InboxButton.tsx:232 | 请先登录 AstroBox 账号（硬编码） | 未登录点击导航图标 |
个人资料
| 触发位置 | 消息 | 说明 |
|---|---|---|
| pages/profile.tsx:218 | err?.message ?? String(err) | 公开资料获取失败 |
| pages/profile.tsx:321 | profile.collections.queueDeviceUnknown | 收藏集入队时无法解析设备 ID |
| pages/profile.tsx:387 | profile.collections.queueAddedSummary + added + ignored | 收藏集批量入队完成 |
| pages/profileEdit.tsx:194 | profile.edit.background.needMedia | 提取颜色时无媒体 URL |
| pages/profileEdit.tsx:208 | profile.edit.background.extractFailed | 颜色提取返回空 |
| pages/profileEdit.tsx:211 | profile.edit.background.extractDone | 颜色提取成功 |
| pages/profileEdit.tsx:240 | profile.edit.board.proRequired | 非 Pro 用户尝试添加看板 |
| pages/profileEdit.tsx:276 | profile.edit.saved | 资料保存成功 |
| pages/profileEdit.tsx:280 | err?.message ?? String(err) | 资料保存失败 |
| pages/profileEdit.tsx:829 | profile.edit.board.linkPreview | 看板预览中点击链接 |
| pages/profileCollections.tsx:108 | profile.collections.titleRequired | 收藏集标题为空 |
| pages/profileCollections.tsx:127 | profile.collections.saved | 收藏集保存成功 |
| pages/profileCollections.tsx:130 | err?.message ?? String(err) | 收藏集保存失败 |
| pages/profileCollections.tsx:141 | profile.collections.deleted | 收藏集删除成功 |
| pages/profileCollections.tsx:144 | err?.message ?? String(err) | 收藏集删除失败 |
二、Rust 后端返回错误
图片/数据工具
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| frontapi/utils.rs:185 | image decode error | 图片解码失败 |
| frontapi/utils.rs:188 | no valid pixels | 图片量化失败 |
| frontapi/utils.rs:212 | invalid image data | Base64 解码失败 |
| frontapi/utils.rs:219 | image download error | 图片下载失败 |
| frontapi/utils.rs:222 | image read error | 图片读取失败 |
| frontapi/utils.rs:225 | image_url or image_data required | 参数验证失败 |
三、WASM / 逻辑层抛错
| 位置 | 错误消息 | 触发条件 |
|---|---|---|
| logic/api/astrobox/request.ts:162 | 你的社交功能已被限制，解除时间：... | 后端返回 social-banned |
| logic/api/astrobox/request.ts:169 | 账号已被封禁：... | 后端返回 user-banned |
| components/resource/detail/Hero.tsx:203 | OfficialV2 device map is not ready | OfficialV2 设备映射未就绪 |
| components/resource/detail/Hero.tsx:840 | clipboard unavailable | 剪贴板不可用 |
四、其他排查建议
| 报错 | 建议操作 |
|---|---|
| image decode error | 确认图片格式正确且未损坏 |
| profile.collections.titleRequired | 确保输入了收藏集标题 |
猫饼干