排错与常见问题

先记下错误信息的行号，再判断问题属于语法、运行、素材、布局还是连接。一次只修一个问题，通常比整体改写更快。

组件或字段找不到

现象	常见原因	处理方式
提示定义 main()	缺少入口、入口不是同步函数	使用 function main() { return ...; }
React is not defined	粘贴了普通网页 React 项目	去掉 React 引入，使用 CapDrive 提供的 JSX 组件
$data.speed 取不到数据	使用了旧的平铺字段	改成 $data.current.speed
某组件不接受某属性	属性放错位置，或版本不支持	查对应参考页；旋转等变换放进 Transform
fetch、window 或 document 不存在	把仪表当成网页运行	仪表不提供浏览器与网络 API

速度变成 0，或格式化时报错

缺测是 null，不是 0。先判断读数是否可用，再格式化：

const speed = $data.current.speed;
const text = speed === null ? '—' : speed.toFixed(1);

Math.round(null) 会得到看似有效的 0，这正是需要显式判断缺测的原因。只有明确要把缺失值当作计算初值时，才使用 ?? 0。

数字、图形被裁切

1. 检查有没有固定得过大的 width、height。
2. 如果用了 CardContent，正文尺寸是否已经扣掉标题与边距。
3. 检查 x/y 是相对哪个父容器，不要把屏幕坐标当作局部坐标。
4. 检查是否启用了 clipped、clip、Mask，以及子元素是否已经超出裁切区域。
5. 在小、中、大和横屏都检查一次。

素材不显示

• source 必须是素材管理给出的完整标记，区分大小写。
• 代码里的示例名称不是你本地文件的自动别名。
• 素材应实际存在，且能被系统解码。
• 先用 contentMode="fit" 和明确的宽高检查。
• 删除素材后，代码中的旧引用需要自己替换。

地图位置、偏移或效果不符合预期

• 默认跟随 MapKit 的当前位置；要跟随传入数据，使用 MapFollowMode.latestData。
• 固定 position 会覆盖跟随设置。
• regionPixelOffset 移动的是可视区域中心，目标点看起来往相反方向移动。
• 地图不能放进像素滤镜、透明度遮罩或循环布局中；材质效果应作为地图旁边的独立叠加层。
• 地图区域识别与瓦片加载可能需要网络与时间。仪表不替 App 获取系统权限。

预览正常，列表却不动

仪表库和选择面板使用保存时生成的静态透明缩略图。实时变化应在预览或已加入仪表盘的卡片中检查；修改后重新保存才能更新列表图。

动画没有运行

检查系统“减弱动态效果”、当前是否处于静态缩略图、组件是否可见，以及目标属性是否支持动画。文字替换用 contentAnimation，数值属性变化用 animations；两者不能互换。

执行超限或画面迟缓

减少循环次数、重复生成的大数组、逐次高频日志和不必要的节点。历史最多 151 个采样，通常无需再次人为创建数万点的曲线。把统计计算放在一次遍历中完成，给重复子节点提供稳定 key。

远程编辑连接断开

先确认手机仍在当前草稿前台、两端网络可互通、地址和端口没有变化。参见远程编辑的逐项检查。

仍无法解决时，保留报错文本、最小可复现代码、App 版本、设备与系统版本。联系 CapDrive 支持，不要仅提供一张看不到行号的局部截图。