常见问题

按“服务 → 安装 → 页面匹配 → Runtime → 任务 → 组件”的顺序检查，先确认失败在哪一步。

dev 启动失败

查看终端第一条错误。确认依赖已安装、入口文件存在、运行命令的目录正确。配置字段的错误应按报出的字段路径修正；端口占用时换端口或关闭占用进程。

--strictPort 会在指定端口不可用时退出。命令参数见CLI 参考。

安装页打开了，但网页没有组件

安装页用于安装脚本。确认脚本管理器已完成安装且启用了脚本，然后打开匹配 @match 的目标网页。

修改 @match 后，检查管理器中的脚本元信息是否更新。

终端没有任务入口

检查 vite.config.ts 是否同时配置了 makoo(...) 和 makooDev()，并使用 makoo dev 启动。

输出重定向或 CI 环境不会显示交互页面，见本地开发。

一直等待 Runtime

确认目标网页已经打开且脚本执行到了 createMakoo()。查看浏览器控制台是否有模块加载或入口执行错误，并确认 dev 服务仍在运行。

任务存在，但组件没有出现

1. 在目标网页控制台用 document.querySelector('你的选择器') 检查目标。
2. 确认组件类型与注册的 Vue/React Adapter 对应。
3. 检查 dom:targetTimeout、artifact:mountFail 等事件及浏览器错误。
4. 如果组件已挂载，检查宿主 CSS、遮挡、位置和可见性。

pending 表示等待目标，idle 表示当前未运行；它们不是完整的错误诊断。通过事件与状态 API可以订阅具体事件。

节点替换后面板消失

检查宿主是否移除了匹配的目标元素。如果需要同一选择器恢复后重新注入，启用 alive 并选择适当 scope。如果只是 URL 改变，仍需由应用决定任务如何切换。见生命周期与清理。

热更新后重复挂载或重复回调

• 在脚本管理器中，只启用当前要测试的那份脚本。
• 检查 createMakoo() 是否在组件渲染或重复回调中被多次调用。
• 如果自定义了 HMR 边界，检查该模块是否清理旧副作用；组件创建的事件和定时器也应在卸载时释放。

更新方式与边界说明见热更新。

GM API 不可用

从浏览器应用代码导入 @makoojs/cli/monkey，不要在 Node 配置中调用。检查脚本管理器是否在当前页面执行脚本，以及实际 metadata 是否声明所需权限。见 Userscript API。

preview 显示旧内容

先重新 build，再 preview；检查两者的 outDir 相同，并确认管理器运行的是新构建脚本。preview 不会自动编译源码。见构建与预览。