错误与排查
没有开发者工具。可用的调试手段有两类：页面中央的红色错误文字，以及宿主启动日志。
页面内错误
| 错误文本 | 含义 | 处理 |
|---|---|---|
cannot open <path> | 文件不存在或路径错 | 核对 app.json 的页面路径与三件套是否齐全。 |
app.json: <detail> | JSON 语法错误 | 不能有注释、尾逗号、单引号。 |
script error: <detail> | JS 异常 | 检查语法错误、未定义的 API 或属性拼写。 |
index.js did not call Page() | 没有调用 Page() | 在脚本顶层直接调用 Page({...})。 |
JSON.stringify failed: ... | data 无法序列化 | 移除函数、循环引用、BigInt 等。 |
page data: <detail> | 序列化结果不是合法 JSON | undefined、函数、循环引用都会导致失败。 |
WXML: <detail> | WXML 结构错误 | 标签成对闭合，或使用自闭合 />。 |
WXSS: missing '{' in WXSS | 样式块语法错 | 检查选择器与花括号。 |
WXML has no renderable root | 没有可渲染节点 | 至少保留一个 view / text。 |
启动日志
miniapp: loading package at <path>
miniapp js [onLoad]: <error>
miniapp js [timer]: <error>- 没有
loading package at：没进入小程序，启动器仍在列表页，或安装失败。 - 有加载日志但页面是红字：WXML / WXSS 解析或 JS 初始化失败。
- 生命周期或事件报错会带
[onLoad]/[onReady]/[timer]前缀。
启动器的问题不写日志，直接看界面：列表加载失败会显示服务器地址与错误文本，空列表显示「商店里还没有小程序」。
常见故障
| 现象 | 原因 |
|---|---|
| 启动器一直显示「正在连接商店…」 | 服务没启动、地址不可达，或卡在超时。 |
| 列表为空「商店里还没有小程序」 | 数据库里没有已发布记录；检查种子导入。 |
下载失败: ... | 下载接口 404 / 超时；确认 /api/v1/miniapps/{id}/download 可访问。 |
安装失败: 安装包必须使用 ZIP_STORED | 用了普通压缩 zip；重新以 STORED 打包。 |
安装失败: 安装包缺少 app.json | zip 里多套了一层目录；包根必须直接是 app.json。 |
屏幕中央红字 cannot open ... | 路径写错或缺少文件，最常见是缺 .wxss。 |
| 文字不显示 | 文本放进了自闭合标签、内容为空、颜色与背景同色，或被压成 0 宽。 |
| 点击没有反应 | 没有用 A 激活焦点；确认元素带 bindtap，且焦点环落在该元素上。 |
| setData 后界面不变 | 补丁对象没有实际变化，或把变更写进了 this.data 而不是 setData 参数。 |
| 布局挤在一起 | 父节点需要 flex-direction: row；检查 flex 简写与宽度约束。 |
| 页面超出画面 | 把内容放进 scroll-view，或用方向键把焦点移出视口以自动滚动。 |
| 样式没生效 | 属性不在支持列表；或选择器用了伪类 / 子代 / 属性选择器。 |
| 图片空白 | 只支持包内绝对路径；确认文件存在且路径以 / 开头。 |
预览检查清单
- 没有红色错误文字。
- 方向键能依次聚焦所有可交互控件，焦点环清晰可见。
- A 能触发按钮与表单事件，B 能从二级页面返回。
- 定时器与
setData能持续更新界面。 - 内容超出时
scroll-view能随焦点自动滚动。 - 调整窗口大小时布局不崩坏（根节点会重新适配）。
对应源码：
miniapp_view.cpp（drawError / loadPackage）、js_runtime.cpp（异常日志）。