linux guide clipboard

Linux 剪贴板历史

当前 Linux 桌面使用 cliphist 保存历史，Quickshell 提供搜索、分类、预览和置顶 UI

打开与使用

在 Niri 中按 Alt-v 打开，也可以从终端执行：

qs-popup clipboard

选中历史后按 Enter 会把内容重新写回系统剪贴板并关闭窗口，随后在目标应用中手动按 Ctrl-v 粘贴

快捷键

快捷键	功能
直接输入	实时搜索
#标签 关键词	按类型标签过滤后搜索
Up/Down 或 Ctrl-p/n	移动选择
Enter	复制选中项并关闭
Alt-p	预览选中项
右键条目	打开预览
Esc	先关闭预览，再按一次关闭面板

条目悬停时可以使用图钉置顶，或使用垃圾桶删除

支持的内容

• 普通文本与代码
• HTML 与富文本
• 图片和 GIF
• 视频缩略图与元数据
• 文件和多文件路径
• 颜色值等可识别文本

列表首屏优先加载，剩余内容分帧解析；图片、MIME 和视频信息在后台异步补全

搜索与排序

置顶项始终排在历史项之前。搜索先匹配关键词，再进行模糊匹配；同一内容同时存在于置顶与历史时只显示置顶版本

默认最多加载 750 条用于面板展示，cliphist 守护进程本身保留最近 5000 条，单条超过 5MB 时跳过

置顶与清空

置顶内容与 cliphist 历史分开持久化：

操作	历史记录	置顶内容
清空面板	清空 cliphist 与临时缓存	保留
删除普通项	从 cliphist 删除	不影响
删除置顶项	不删除历史副本	取消置顶并清理快照
复制置顶项	不依赖原 cliphist 条目	从持久快照恢复

因此清空历史不会丢失收藏内容

存储位置

用途	路径
配置	~/.config/quickshell/clipboard/
置顶清单	~/.local/share/qs-clipboard/pins/pins.json
置顶图片	~/.local/share/qs-clipboard/pins/
临时解码与缩略图	$XDG_RUNTIME_DIR/qs-clipboard/
同步防竞态 hash	$XDG_RUNTIME_DIR/clipboard-sync/last_hash

临时缓存重启后自动消失，置顶内容长期保留

Wayland 与 X11

复制时优先使用 wl-copy 回写 Wayland 剪贴板，同时自动探测 X11 display 并用 xclip 兜底。图片会尽量保留 MIME；文件场景可写为 text/uri-list

写入前会记录内容 hash，避免同步守护进程把刚复制的条目再次加入历史

常用环境变量

变量	默认值	功能
QS_POS	center	面板位置
QS_TARGET_OUTPUT	首个屏幕	指定输出名称，例如 DP-1
QS_CLIPBOARD_LIST_LIMIT	750	最大历史加载数量
QS_IMAGE_FILE_MODE	auto	图片文件使用 uri、image 或自动策略

依赖与排错

核心依赖：Quickshell、cliphist、wl-clipboard 和 file。视频预览需要 ffmpeg 或 ffmpegthumbnailer，X11 回写需要 xclip

常见问题：

• Alt-v 无响应：终端运行 qs-popup clipboard 查看启动错误
• 面板为空：确认 cliphist systemd user service 正在运行
• 图片没有缩略图：检查运行时缓存目录、file 和图片解码结果
• 视频没有预览：检查 ffmpegthumbnailer 或 ffmpeg、ffprobe
• X11 应用无法粘贴：确认 xclip 存在，并检查有效 DISPLAY
• 置顶内容异常：检查 pins.json 和对应快照文件权限