Misc. bug: Async clipboard support for images pasted under Wayland

问题场景

用户在 Linux 的 Wayland 会话下运行 llama.cpp 的 WebUI（llama-server），尝试将剪贴板中的截图或图片直接粘贴到聊天输入框（ChatForm.svelte）中。传统事件（event.clipboardData.files）无法获取到图片数据，且 Chromium 浏览器（Brave）在键盘 Ctrl+V 时可能完全不会触发 paste 事件。

报错原文

Misc. bug: Async clipboard support for images pasted under Wayland

注意：该 Issue 为功能请求/缺陷报告，没有具体的错误日志输出（Relevant log output 为空），核心问题表现为“粘贴图片无反应”或“剪贴板图片无法作为附件插入”。

原因分析

可能原因一（浏览器权限策略）：Chromium 内核浏览器（如 Brave）在非 HTTPS 或证书不受信任的情况下，会阻止 navigator.clipboard.read() 的异步读取。

可能原因二（Wayland 剪贴板协议差异）：Wayland 下，传统 paste 事件的 clipboardData.files 通常不包含图片位图数据，需要异步 Clipboard API 才能读取；但 Chromium 在 Wayland 下对 Ctrl+V 键盘快捷键的 paste 事件支持不完整，导致事件路径无法触发。

可能原因三（实现不完整）：官方代码中缺少对异步 Clipboard API 的回退逻辑，导致所有依赖事件读取的路径全部失败。

环境排查

• llama.cpp 版本：确认是否为 9892 或更新版本（Issue 报告为 ee445f93d）。
• 操作系统：确认是否在 Linux 下使用 Wayland 会话（可通过 echo $XDG_SESSION_TYPE 检查）。
• 浏览器：确认是否为 Chromium 内核（Chrome、Brave、Edge 等）；Firefox 不受影响，可用来对比排除环境问题。
• SSL 环境：确认 WebUI 是否通过 HTTPS 访问，或者仅通过 localhost 访问。
• 剪贴板内容：确认剪贴板中确实存在图片（而非仅文字或文件路径）。

解决步骤

1. 首先确认是否为浏览器安全策略问题：如果通过远程 IP 或域名访问 WebUI，请尝试改用 https://localhost:8080 或 http://localhost:8080 访问（localhost 被视为安全上下文），确认是否能正常粘贴图片。
2. 如果本地访问仍无法粘贴，请点击输入框旁边的“+”或“添加附件”下拉菜单，查找是否有“Paste image from clipboard”按钮。该按钮通过点击事件触发异步读取，可绕过键盘 Ctrl+V 在 Wayland 下不触发 paste 事件的问题。
3. 如果按钮路径不可用或未实现，可尝试应用 Issue 中提供的外部补丁（0001-webui-support-pasting-images-via-async-clipboard-API.patch）。该补丁为读取剪贴板图片增加了异步回退逻辑，但在 Brave 下仍需处理 SSL 证书权限问题。
4. 如果你的浏览器是 Firefox，直接使用 Ctrl+V 粘贴，确认问题是否仅出现在 Chromium 下。若 Firefox 正常，则基本可确定是 Chromium/Wayland 的兼容性问题。
5. 在浏览器地址栏输入 about:config（Firefox）或 chrome://flags（Chromium）检查“Clipboard”相关权限设置，确保没有强制禁用异步剪贴板读取。

验证方法

打开 WebUI 聊天界面，使用系统截图工具截取一张图片，然后分别尝试以下操作：

• 直接按 Ctrl+V 粘贴，观察图片是否作为附件出现在输入框中。
• 点击“Paste image from clipboard”按钮（如果存在），观察图片是否作为附件出现。
• 在 Firefox 中重复上述操作，对比结果；如果在 Firefox 中正常而在 Chromium 中失败，则确认是浏览器兼容性问题。

参考来源

ggml-org/llama.cpp #25381

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。