10. PinSlip 常见问题与故障排查

8/1/2026

10. 常见问题（FAQ）

这一章汇总了最常见的问题与排查思路。
找不到答案？欢迎到 GitHub Issues 告诉我们。

安装与启动

macOS 提示「应用已损坏」

原因：当前版本未签名（v1.0.1 起，签名后无需此操作）。

任选一种方式绕过：

  1. 在「应用程序」里右键 PinSlip → 打开

  2. 在终端执行：xattr -cr /Applications/PinSlip.app

Linux 下全局快捷键不响应

原因：Wayland 会话下，对原生窗口的全局快捷键不响应。

方案：使用 X11 会话登录；X11 行为符合预期。

GNOME 桌面看不到托盘图标

原因：GNOME 默认不显示应用指示器。

方案：安装 AppIndicator and KStatusNotifierItem Support 扩展即可。

Windows 安装版「开机自启」灰

原因：dev 模式（pnpm dev）不支持写注册表。

方案：用安装版（PinSlip-Setup-*.exe）安装后才有此开关。

首次启动很慢

原因：Go 服务首次编译 + 索引全量重建。

说明：二次启动秒开。空 vault 通常几秒；有几千条便签可能要 1~2 分钟。

便签找不到 / 出屏

便签跑出屏幕外

原因：拔掉外接屏 / 改了显示器分辨率。

方案：重开应用 → PinSlip 自动回到可见区。

主界面不见了

方案：

  • 系统托盘左键 PinSlip 图标 → 切换显示

  • 快捷键 Ctrl+Shift+N 重新呼出速记

  • 重启应用

Windows 任务栏里都找不到

方案：每个便签在任务栏都有图标；如果不在，看下托盘有没有「隐藏」。

删除与恢复

删错了怎么办

方案：从 .trash/ 把文件拖回 notes/；PinSlip watcher 自动识别并重建索引。

整个文件夹被删了

方案：从 .trash/整树/ 把整个文件夹拖回 notes/。

想物理删除某个便签（不进回收区）

方案：从 .trash/ 直接删除文件（绕过 PinSlip 删除逻辑）。

一般不建议这样做，回收区存在的意义就是兜底。

搜索

搜索不到某些关键词

排查：

  • 纯符号串很可能漏

  • 试试标签或标题词（**搜索权重最高）

  • 关键词在正文的话，权重比较低，可能排不到第一

搜索结果太多

方案：加更多修饰词；或用标签搜索。

Markdown 与图片

粘贴的图片不显示

排查：

  • 检查 <vault>/attachments/ 目录权限

  • 外部编辑器（Obsidian / VS Code）是否支持相对路径 ../attachments/

  • <img> 标签里的路径是否带中文 / 空格（不应有）

任务框点不动

排查：

  • 鼠标光标需要在任务框的方框上

  • 当前便签是不是处于折叠状态（折叠时任务框可点但区滚动为目标）

字号缩放按钮消失

原因：窗口太窄，按优先级被收起。

方案：

  • 拉宽窗口

  • 点 ⋯ 菜单找「字号缩放」

Git 同步

认证失败

排查：

  • token 是否过期？

  • 仓库地址是否含 .git 后缀？

  • 是否有写权限？

  • 用户名是否填错？

同步卡住

原因：网络 / 远端问题。

方案：

  • 状态面有 lastError

  • 指数退避 1m→5m→15m 是正常现象

同步失败反复

排查：

  • 网络能否访问 GitHub / GitLab / cnb？

  • DNS 污染？试试改 hosts

  • 国内网络拉不下来？考虑换到 cnb 或自建 Gitea

「待解冲突」出现

方案：打开冲突便签 → 选「全部用本地 / 全部用远端 / 手动编辑」→ 保存解决。

详见 06-Sync → 冲突解决。

MCP

客户端连不上 MCP

排查：

  • 检查 <vault>/.pinslip/mcp.json 是否存在

  • pid 是否存活（与 PinSlip 进程一致）

  • 设置里 MCP 开关是否开

  • 客户端 URL 有没有用 127.0.0.1 而不是 localhost

工具调用 404

原因：MCP 开关关闭或服务未启动。

方案：

  • 设置 → MCP 服务 → 打开开关

  • 重启 PinSlip

工具调用超时

方案：

  • 检查 Go 服务是否卡住（重启 PinSlip）

  • 检查是否有大量便签在重建索引

浏览器扩展

扩展连不上桌面

排查：

  • 桌面端 PinSlip 是否在运行

  • 选项页里端口是否对得上 mcp.json 里的 port（默认 17639，可能不一致）

  • 试「重连探测」按钮

右键菜单没有 PinSlip 项

排查：

  • 扩展是否启用了「在上下文菜单」权限

  • 是否在不允许注入的页面（Chrome Web Store / 设置页等）

性能

大 vault 打开慢

方案：

  • 检查 .pinslip/pinslip.db 是否被外部程序占用（应没有）

  • 几千条便签以内一般无感

  • 及时使用回收区清除无用便签

编辑卡顿

排查：

  • 单张便签过长？拆分或归档到外部文件

  • 浏览器扩展是否在持续读写磁盘

其它

macOS 托盘图标尺寸异常

说明：v1.0.0 早期版本有「大图撑爆菜单栏」问题；v1.0.1 已修复。升到最新版本。

怎么完全卸载

  1. macOS：拖到废纸篓

  2. Windows：设置 → 应用 → 卸载

  3. Linux：sudo apt remove pinslip 或直接删除 AppImage

  4. 删除 vault 目录（提前备份）

数据归谁

你。 PinSlip 只是个壳，你的便签始终以 Markdown 文件存在于你的磁盘上。
即使 PinSlip 不做了，Obsidian / VS Code / Typora 任何编辑器都能打开。
这就是 PinSlip 与生俱来的设计哲学。