校验错误与排障

配置校验规则、字段路径错误、加载与渲染问题、入口和应用问题的排查方法。

错误分类

壁纸编辑器把问题分为四类：

配置获取或 JSON 语法错误；
配置字段运行时校验错误；
素材或蒙版加载错误；
渲染、导出或设备应用错误。

应先解决最早出现的类别，因为后续阶段依赖前一阶段成功。

配置获取错误

`壁纸配置加载失败（状态码）`

检查：

configUrl 是否真实存在；
GitHub 地址是否指向文件而不是目录；
当前官方源是否可访问；
私有仓库是否要求未提供的认证；
服务是否返回 301/302 后仍可跨域读取；
GitCode 镜像是否只用于支持的官方仓库。

`壁纸配置不是有效的 JSON`

检查：

是否返回了 HTML 404、登录页或限流页面；
JSON 是否包含注释、尾逗号、单引号或未转义字符；
GitCode API 响应是否完整；
文件编码是否为正常 UTF-8。

字段校验错误格式

运行时不会把远程 unknown 直接强制转换为 TypeScript 类型。解析器会尽量遍历整个配置，聚合所有发现的问题：

壁纸配置无效：
- templates[0].layers[1].src 必须是非空字符串
- templates[0].layers[1].opacity min 不能大于 max
- templates[0].layers[1].blendMode.default 必须包含在 options 中

路径使用实际数组索引，可以直接定位到模板和图层。

根对象检查

问题	结果
`version` 存在但不是 1	`version 当前仅支持版本 1`
`templates` 不是数组	`templates 必须是非空数组`
`templates` 为空	`templates 不能为空`
`shared` 存在但不是对象	`shared 必须是对象`
模板 ID 重复	对应 `templates[N].id 不能重复`

注意：完全省略 version 会进入旧格式兼容模式，不会报告版本缺失。

模板检查

id、deviceKey、watchface.name 必须是非空字符串。
watchface、canvas 必须是对象。
Canvas 宽高必须是有限数值且大于 0。
aliases 必须是字符串数组。
layers 在 Version 1 必须是数组，但允许空数组。
同一模板内图层 ID 不能重复。
frame 宽高必须大于 0；x/y/radius 当前只要求有限数值。
CSS 颜色必须有效。

图层检查

类型

现代 type 必须是 wallpaper、asset、tint、text 或 glass。overlay 会兼容为 tint，旧 source.type 也可推断类型。

Asset

asset 必须有非空 src。缺失时路径会指向：

templates[N].layers[M].src

文字图层

font.options[].id 必须是非空且不重复的字符串。
font.options[].axes[].tag 必须是 4 字符字符串，且同一选项内不能重复。
字体轴的 min/max 必须为有限数值且 min <= max；default 缺省取中点，必须落在范围内。
font.default 必须匹配某个选项的 id。
maxLength 必须是正整数。
textBox.width/height 必须大于 0。
fontSize 必须大于 0，lineHeight 必须大于 0。

玻璃图层

geometry.type 必须是 rounded-rect 或 circle。
几何宽高和圆角必须为正数；圆角会被限制在宽高一半以内。
material.blur 在 [0,100] 语义下使用，refraction clamp 到 [0,4]，lightAngle clamp 到 [0,360]。
高光和阴影混合模式必须是支持的 12 种模式之一。
material.tint 必须是有效颜色。
surfaceProfile 目前只实现 apple，bubble 预留。