调试与排错
日志
js
wad.log('hello', { a: 1 }, [1, 2]);日志会进入：
- App →「插件」页的日志面板（可按插件筛选）；
- 面板自身的 console。
日志页支持实时轮询、清空、按插件下拉过滤。发布前记得删掉调试输出。
常见错误
| 现象 | 原因 | 处理 |
|---|---|---|
安装返回 E_SYNTAX | 内联脚本有语法错误 | 预检就会拒绝，按提示行号修 |
HOST_ERROR + 未注册提示 | 调用了未注册的 Skill | 确认 register 在逻辑层执行、名字一致 |
HOST_ERROR + 异常文本 | Skill 内抛异常 | 看 message，补参数校验 |
TIMEOUT | 6 秒没有响应 | 检查是否在逻辑层做了长耗时操作 |
SEND_FAILED | 帧超过 200 KB | 分页取，或改走 net.body |
BUS_DISCONNECTED | 总线断开 | 等 wad.ready 重连后再调 |
CDP_DISABLED | 调试通道关闭 | 先开启调试，插件才能注入 |
| 面板空白 | 插件未启用 / 全局开关关闭 | 检查两个开关 |
| logic 不执行 | 脚本没写 type="text/wad-logic" | 补上 type |
| render 不执行 | 页面还没有 target | 等页面加载完，或切换一次页面 |
生命周期陷阱
重复 attach
安装、更新、启停都会重新触发 attach。初始化要幂等：
js
let timer = null;
wad.on('attach', function () {
clearInterval(timer);
timer = setInterval(tick, 1000);
});
wad.on('detach', function () {
clearInterval(timer);
timer = null;
});DOM 残留
停用 / 卸载不会自动还原你改过的 DOM。所有插入、修改都要在 detach 里回滚。
storage 异步
js
// 错误：拿到的是 Promise
const cfg = wad.storage.get('cfg');
// 正确
const cfg = (await wad.storage.get('cfg')) || {};面板状态丢失
面板每次打开都是新的 iframe。需要跨次保留的状态放 wad.storage。
在 App 里自检
装好插件后，按这个顺序确认：
- 插件页能看到条目，版本、作者正确；
- 打开小程序，插件日志出现
attach； - 面板能打开，
wad.ready正常； - 切一次页面，
pageChange有输出； - 停用插件，
detach有输出且页面恢复。
日志页可以按插件筛选，出问题时先看这里。
手动验证清单
- [ ] 安装后能在列表里看到，图标、版本、作者正确
- [ ] 面板能打开，
wad.ready正常 resolve - [ ] 逻辑层
wad.register的 Skill 能被面板调用 - [ ] 渲染层注入后页面出现预期变化
- [ ] 切换小程序后插件重新注入，没有重复 UI
- [ ] 关闭插件后 DOM 恢复
- [ ] 卸载后插件目录与网络规则被清理
性能建议
- 面板不要一次性渲染上千行，用分页或虚拟列表；
- 不要在
network事件里同步做重活，先入队再批量处理； - 逻辑层 Skill 保持短小，长任务拆分或放面板侧；
- 渲染层避免高频读写布局属性，防止掉帧。