表盘编辑报错
表盘编辑、应用、预览过程中可能出现的报错、解决方案及说明
本文档汇总 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: {err} | 异步解析 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 | 确认文本内容不为空，且字体支持对应字符 |