wayscriber 是一款用 Rust 编写的 Linux/Wayland 实时屏幕标注工具，可以当作白板或黑板，支持绘画批注、放大演示、截图捕获等功能。当你遇到 wayscriber overlay 不显示、KDE 透明失效或 daemon 启动失败时，这份故障排查清单可以帮你按顺序快速定位问题，几分钟内恢复正常运行。

排查总览：一张表定位故障

先跑一遍这三个命令，基本就能确定问题属于哪一类 👇

echo $WAYLAND_DISPLAY systemctl --user status wayscriber.service journalctl --user -u wayscriber.service -n 50

故障一：Wayscriber overlay 不显示怎么排查

1. 确认当前是 Wayland 会话

wayscriber 依赖 Wayland 的wlr-layer-shell协议创建覆盖层，X11 下完全不工作，这是它最常见的"不显示"原因。

echo $WAYLAND_DISPLAY

• 有输出（如wayland-0）→ 是 Wayland 会话，继续第 2 步
• 输出为空且echo $XDG_SESSION_TYPE为x11→ 切换到 Wayland 登录会话，否则 overlay 不可能出现

2. 确认 compositor 支持 layer-shell

官方平台支持情况（来自 README.md 的 Platform support 表）：

如果你用的是非常小众的 compositor，先确认它是否实现了wlr-layer-shell。

3. 用日志模式启动，直接看报错

RUST_LOG=info wayscriber --active

如果终端里出现 TOML 解析错误，说明配置文件损坏，参考下面"配置问题"一节；如果是 Wayland 连接失败，日志里会直接点明协议缺失。

4. 配置文件的隐蔽故障

配置在~/.config/wayscriber/config.toml，常见问题是手改后引入语法错误导致启动即退：

ls -la ~/.config/wayscriber/config.toml RUST_LOG=info wayscriber --active # 留意 TOML 错误

没有配置也可以先跑起来——官方提供了完整示例，见 config.example.toml，全部字段参考 docs/CONFIG.md。

故障二：KDE Plasma 上 overlay 透明失效 / 画面模糊

这是 KDE 用户的经典问题，官方文档给出了明确结论：Better Blur DX这类模糊特效会把 wayscriber 的透明 overlay 一起"糊"掉。

方案 A：把 wayscriber 加入 Better Blur DX 的例外列表

1. 打开系统设置 → 窗口管理 → 桌面特效
2. 点击 "Better Blur DX" 旁的配置按钮
3. 进入Force Blur选项卡
4. 在窗口类列表中加入wayscriber
5. 确认勾选了Blur all except matching（模糊除匹配外的一切）
6. 点击应用

方案 B：换回标准模糊特效

如果不想维护例外列表：在桌面特效中禁用 "Better Blur DX"，改用标准的 "Blur" 效果即可。

如何确认 wayscriber 的窗口类名

如果上面的列表里要填的 class 名不确定，启动一次 wayscriber 后运行（注意在 2 秒 sleep 结束前把 overlay 调出来）：

sleep 2; qdbus org.kde.KWin /KWin queryWindowInfo | grep resourceClass

另外提醒：KDE 上 Freeze 和 Zoom 依赖xdg-desktop-portal-kde的截图 portal，首次使用可能弹出权限确认，请允许授权，否则相关功能会"看起来像没生效"。

故障三：Wayscriber daemon 启动失败怎么办

daemon（后台守护进程）是日常使用推荐模式：systemd用户服务常驻后台，按一个全局快捷键就能呼出 overlay，且会话状态在开关之间保留。

1. 检查服务状态

systemctl --user status wayscriber.service

服务未启用是最常见原因，一键启用：

systemctl --user enable --now wayscriber.service

也可以不用命令行：打开wayscriber-configurator，进入Background Mode选项卡，点击Install Service（已安装则显示Update Service），再点击Start Service，详见 docs/SETUP.md。

2. 跟踪日志找失败原因

journalctl --user -u wayscriber.service -f

重启服务后观察输出：

systemctl --user restart wayscriber.service journalctl --user -u wayscriber.service -f

3. 一个容易被忽略的细节：WAYLAND_DISPLAY 检查

服务单元文件 packaging/wayscriber.service 里有一行前置检查：

ExecStartPre=/bin/sh -c '[ -n "$WAYLAND_DISPLAY" ] && [ -S "$XDG_RUNTIME_DIR/$WAYLAND_DISPLAY" ]'

意思是：如果WAYLAND_DISPLAY为空、或对应的 Wayland socket 不存在，daemon 会直接拒绝启动（退出码 75 被标记为成功退出，不会无限重试）。如果你用 lingering 让服务在登录前就运行，此时还没有图形会话，daemon 自然起不来。解决办法：

• 只希望"登录后自动启动"→ 保持默认即可，用户服务本来就在登录时拉起
• 确实需要登录前运行 →loginctl enable-linger $USER，但要接受 daemon 在图形会话前不可用的事实

4. 重启后 daemon 消失

已启用的用户服务会在你登录桌面时启动。如果重启+登录后仍然没有，回到上面第 2 步看 journal 日志，基本都能定位到具体错误。

5. 手动模式验证

不想排查 systemd 时，可以先手动起 daemon 验证二进制本身没问题：

pkill wayscriber sleep 0.5 wayscriber --daemon & sleep 0.5 pgrep -x wayscriber && echo "✓ daemon 已启动"

仓库里也提供了等价的脚本 tools/reload-daemon.sh，效果相同。

6. 日志文件去哪找

--active和--daemon都会把带日期的日志写入：

~/.local/share/wayscriber/logs/

排查 Freeze/Zoom 类捕获问题时，可以在 daemon 的启动环境里设置RUST_LOG=info,wayscriber::capture_diagnostics=trace获取更详细的输出，改完后记得重启 daemon 让新环境生效。

附加排查：快捷键按了没反应

overlay 不显示之外，"按键没反应"也很常见，按此顺序检查：

1. 重复绑定：同一个快捷键绑了两次（比如两份SUPER, D），toggle 会触发两下、等于没按。全局只保留一条绑定。
2. compositor 找不到二进制：快捷键环境有时解析不了PATH里的wayscriber，改用绝对路径：command -v wayscriber，然后把路径填进绑定。
3. 改完配置没重载：Hyprland 用户执行hyprctl reload。
4. 多份二进制冲突：type -a wayscriber看是否存在/usr/local/bin与/usr/bin两份，只保留一份，见 docs/SETUP.md 的 Verification 一节。

各桌面环境的快捷键配置示例（Hyprland Lua / GNOME 自定义快捷键 / KDE 命令脚本）都在 docs/SETUP.md 中，照抄即可。

常用环境变量速查

排查完成后的自检清单

✅echo $WAYLAND_DISPLAY有输出 ✅systemctl --user status wayscriber.service显示active (running)✅ 按快捷键能呼出 overlay，RUST_LOG=info启动无 TOML/协议报错 ✅ KDE 用户已处理 Better Blur DX 例外设置 ✅ 只保留一条全局快捷键绑定

按这份清单走完，overlay 不显示、KDE 透明失效、daemon 启动失败这三类 wayscriber 故障基本都能解决。完整的会话管理 CLI 用法可继续参考 examples/session-manager.md，全部配置项参考 docs/CONFIG.md。