Skip to content

调试与常见问题 ​

插件不加载、搜不到、调用报错时,按这一页排查。

调试手段 ​

开发服务与热更新 ​

开发版从 development.main 加载页面,改源码即时刷新。改了 plugin.json 要在开发者工具里按 ⌘ R 重新加载;改了 Node 后端要退出插件(插件菜单「结束运行」)再打开。

看日志 ​

插件页面的 console.* 输出、未捕获的错误,以及 Node 后端的 console.* 和子进程输出,都会写进 lingtools 的日志文件:

系统日志位置
macOS~/Library/Logs/lingtools/lingtools.log
Windows%LOCALAPPDATA%\lingtools\logs\lingtools.log

页面的日志标记为 plugin::<插件名>::page,Node 后端的标记为 plugin::<插件名>(开发版的插件名带 dev-)。页面日志有限速:每个页面每秒最多 50 条、每分钟最多 256 KiB,超出的会合并成一条「丢弃 N 条」,不要在循环里大量打印。

bash
# macOS:只看自己插件的日志
tail -f ~/Library/Logs/lingtools/lingtools.log | grep 'plugin::dev-word-count'

页面的开发者工具 ​

目前只有 lingtools 的开发构建能在插件菜单里打开插件页面的开发者工具(DevTools),正式版没有这一项。在正式版里调试,以日志为主;纯界面问题也可以直接用浏览器打开开发服务地址调样式(此时没有 window.ling,涉及 API 的代码需要自己加判断)。

让 AI 帮你测试 ​

在 lingtools 设置的「MCP」里打开服务,并把它接入 Claude Code、Cursor 等 AI 客户端后,AI 可以:打开你的插件、截图、读取页面结构、点击和填写、按键、读取日志。适合让 AI 按步骤复现问题、跑一遍回归。

插件装上了但搜不到 ​

  1. plugin.json 不合法:任何不认识的字段、不合法的值、引用的文件不存在都会导致插件不加载。开发者工具的项目列表会显示目录状态和原因;也可以对照 plugin.json 逐项检查,用 PluginManifest 类型校验。
  2. 入口限定了平台:platform 不包含当前系统时,入口不出现。
  3. 指令被用户禁用:插件市场详情页里可以禁用单条指令。
  4. 匹配指令不在主结果里:匹配指令只出现在「匹配指令」分组,并且只在内容符合规则时出现;window 指令只在搜索框为空时参与。
  5. 开发版没了:开发版只在本次运行有效,重启 lingtools 后要重新安装。

页面空白或 404 ​

  • 开发版:开发服务没启动,或端口和 development.main 不一致(建议 Vite 配 strictPort: true);development.main 必须以 / 结尾。
  • 正式版:没执行 pnpm build;main 路径写错;Vite 没配 base: './',资源按绝对路径加载失败。

常见错误码 ​

API 调用失败时以带 code 的错误 reject,message 是中文原因。

错误码常见原因怎么办
forbidden没有声明权限,或用户关掉了;或者在不允许的地方调用(如自建窗口里调用 outPlugin、搜索卡片的 run 里粘贴到前台)补权限;检查调用位置
invalid_params参数不合法看 message,对照 API 文档
not_found文件、文档、入口不存在
permission_denied系统层面没有授权(如 macOS 没给辅助功能、屏幕录制权限)提示用户去系统设置里授权
unsupported当前平台不支持用 isMacOS() 等判断后再调用
unavailableNode 后端没就绪、FFmpeg 未安装且用户取消了下载等 onNodeReady;提示用户
busy同类操作正在进行(如已经在截图)稍后再试
timeout超时
aborted被取消(页面或插件关闭、调用 kill())
method_not_foundlingtools 版本太旧,没有这个方法写 minAppVersion
internallingtools 内部错误看日志

ling.db 的写操作不 reject,失败通过返回值的 error / name 告知,见 数据存储。

其他问题 ​

Esc 被 lingtools 当成退出插件了。 在 keydown 里处理 Esc 时调用 event.preventDefault(),lingtools 就不会再退出插件。

插件里的快捷键不生效。 ⌘ /(插件菜单)、有下拉附件时的 ⌘ P 以及用户设置的全局快捷键会被 lingtools 占用,换一个组合。

退到后台再回来,状态丢了。 插件默认退出即销毁。需要保留就在 plugin.json 写 pluginSetting.runInBackground: true,但更稳妥的做法是把状态存进 dbStorage。见 插件运行模型。

macOS 上 Node 后端找不到命令。 从访达启动的 lingtools 没有终端里的 PATH,调用外部命令时写绝对路径。

多个实例数据互相覆盖。 多实例插件的实例共享数据,同一个键后写的覆盖先写的,需要自己按实例区分键名。