常见问题排查

浏览页看不到我刚上传的 Mod

1. 确认上传成功（返回 200 { ok: true }；409 表示 id 已存在）
2. 直接查接口：打开 https://mods-findor-cheat.pages.dev/api/list-mods，应能看到你的记录
3. 回到 Mods → 浏览 点 刷新，或在控制台执行：

await findorCheat.modLoader.refreshRemoteMods();
findorCheat.modLoader.listAvailable().map(m => m.id);

浏览页列表 = registry.json 种子 + /api/list-mods 上传，二者会按 id 去重。若接口里没有你的记录，说明写入 KV 失败（检查上传返回值与 MODS_REGISTRY 绑定）。

安装失败：Manifest not found: <id>

• 种子 Mod：必须存在 <mods 站点>/mods/<id>/manifest.json
• 上传的 Mod：没有 manifest 时会用上传元数据合成（main = 上传填写的 url）。若仍然失败，通常是 url 打不开（跨域、404、非 http(s)://）

// 手动检查
await fetch('https://mods-findor-cheat.pages.dev/mods/hello-world/manifest.json').then(r => r.status);

日志里出现 onLoad 失败 / onEnable 失败

加载器会捕获钩子里的异常并打印 [Mod:<id>] …。启用阶段抛错会回滚安装（卸载代码缓存并从已安装列表移除），因此要保证 onEnable 尽量原子：先做不会失败的事，再注册监听。

事件不触发

• 事件名必须完全一致（区分大小写），清单见事件清单
• 在 onEnable 里订阅：ctx.events 的监听会在 ctx.dispose() 时被清空，onLoad 里订阅不会在禁用后保留
• 全局事件由 cheatEventBus 桥接；若事件发生在 Mod 加载之前（例如 code:webpackReqReady），你收不到，需要在后续动作里轮询状态

命令没反应

• 完整命令名是 <modId>:<name>：例如 Mod id 是 my-mod、注册名 delay，则应输入 /my-mod:delay 500
• args 校验不通过时命令不会执行：args: 0 不能带参数，args: 2 必须正好 2 个，args: -1 至少 1 个
• 检查是否真的注册成功：

Object.keys(findorCheat.commands).filter(k => k.startsWith('my-mod:'));

存储读到旧值 / 想清空

存储按 Mod id 隔离（findor-mod-storage:<id>）：

// 在 Mod 内部
ctx.storage.clear();
// 控制台
localStorage.removeItem('findor-mod-storage:my-mod');

改了 Mod 的 id 等于换了一个存储空间，旧数据不会跟过来。

我声明了 permissions，为什么还能调用别的能力？

permissions 目前是声明式的：加载器会保存它，但不会拦截调用。请自觉只声明并使用真正需要的能力，便于他人审计你的 Mod。

上传返回 400 / 409 / 500

状态	原因
400	缺少 id/name/url；id 不符合 ^[a-z0-9][a-z0-9-]*$；url 不是 http(s):// 开头
409	id 已存在（响应里带 existing 记录）；换一个 id，或先用管理员 token 删除
500	KV binding missing (MODS_REGISTRY) —— 部署未绑定 KV；或 KV 写入异常

卸载后有残留吗？

正常卸载会：执行 onCleanup → 清事件/协议钩子/UI 页面/命令 → 删除已安装记录与代码缓存。若你自建了 setInterval / requestAnimationFrame / 全局变量，请务必在 onDisable（或 ctx.onCleanup）里清理。

常用调试命令

const L = findorCheat.modLoader;
L.listAvailable().map(m => ({ id: m.id, installed: m.installed }));
L.listInstalled();
await L.install('hello-world');
await L.enable('hello-world');
await L.disable('hello-world');
await L.uninstall('hello-world');
findorCheat.modFeatures;          // 各 Mod 的 features 容器

还能看到别的排查思路吗？

• 控制台过滤 [Mod: 前缀可只看 Mod 日志
• ctx.logger.debugEnabled = true 打开 debug 级输出
• 先只保留 ctx.logger.log('ok')，确认 Mod 能加载，再逐步加功能

下一步：ctx 全量 API · 发布与安装