WSL2 图片粘贴问题调研与解决方案

核心问题

在 Windows WSL2 环境下运行 Claude Code，无法通过 Ctrl+V 粘贴截图。这是一个影响所有 WSL2 用户的已知 bug，至今（2026-05）未被官方完整修复。

根因分析（三层问题叠加）

第一层：键位拦截

Claude Code 在 Linux/WSL 下绑定 ctrl+v 触发 chat:imagePaste，但 Windows Terminal 会先拦截 Ctrl+V 做文本粘贴，按键根本传不到 Claude Code。

Claude Code 源码中的平台判断逻辑：

Tf1 = Z8() === "windows" ? "alt+v" : "ctrl+v"

WSL2 报告为 "linux"，所以绑的是 ctrl+v，被 Windows Terminal 吞掉。

第二层：格式识别

Windows 截图工具（Win+Shift+S、微信截图等）存入剪贴板的格式是 image/bmp。WSLg 的 Wayland 剪贴板桥将 Windows 的 CF_DIB/CF_BITMAP 重新导出为 image/bmp。

Claude Code 的 checkImage 命令只 grep 以下格式：

grep -E "image/(png|jpeg|jpg|gif|webp)"

image/bmp 不在列表中，检测直接返回"无图片"。

此问题已在 #25935 修复（v2.1.47+），添加了 bmp 到 grep 模式。

第三层：BMP 解码静默失败（仍未修复）

即使通过了格式检测，WSLg 转发的 BMP 使用 BI_BITFIELDS 压缩格式（compression value = 3），Claude Code 内置的 sharp/libvips 库无法解码这种格式。

关键代码路径：图片保存后进入 JNH 后处理管道，尝试 BMP→PNG 转换，解码失败后 catch { return null } 静默吞掉错误，UI 显示"No image found in clipboard"——与实际失败原因完全无关。

此问题在 #50552 追踪，截至 2026-05 仍为 open 状态。

相关 GitHub Issues

社区解决方案对比

方案一：wl-paste thin wrapper（@bfishman）

原理：在 /usr/local/bin/wl-paste 放一个 wrapper 脚本，拦截 BMP 格式并通过 ImageMagick 转换为 PNG。

优点：

• 零后台进程
• 不污染剪贴板
• 不替换整个管道

缺点：

• 依赖 WSLg 剪贴板桥工作正常（部分终端下不稳定）
• Claude Code 内置 sharp 管道仍可能在后续步骤失败（#50552）
• 需要安装 imagemagick

配置：

1. 创建 wrapper 脚本拦截 --type image/png 请求
2. ~/.claude/keybindings.json 绑定 alt+v → chat:imagePaste

方案二：wsl-screenshot-cli（@Nailuu）✅ 采用

原理：Go daemon + 持久 PowerShell 子进程，直接通过 .NET API 读取 Windows 剪贴板，完全绕过 WSLg。

优点：

• 绕开所有中间环节（WSLg、wl-paste、sharp），最可靠
• 同时保留三种剪贴板格式（文本路径 + 位图 + 文件），不破坏 Windows 侧粘贴
• 支持所有截图工具（Win+Shift+S、微信截图、ShareX 等）
• WSL 侧单 binary，Windows 侧零安装

缺点：

• 常驻后台进程（Go daemon + PowerShell 子进程）
• 需要持续轮询（250ms 间隔）

使用流程：

1. 截图（任何方式）
2. daemon 检测到新图片 → 保存为 /tmp/.wsl-screenshot-cli/.png → 同时将路径写入文本剪贴板
3. 在 Claude Code 中 Ctrl+Shift+V（终端文本粘贴）→ 粘入文件路径
4. Claude Code 通过文件路径读取图片

安装：

curl -fsSL https://nailu.dev/wscli/install.sh | bash

启停：

wsl-screenshot-cli start --daemon   # 启动
wsl-screenshot-cli stop             # 停止
wsl-screenshot-cli status           # 状态

Claude Code Hooks 自动启停（~/.claude/settings.json）：

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "wsl-screenshot-cli start --daemon --quiet 2>/dev/null; true"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "wsl-screenshot-cli stop 2>/dev/null; true"
          }
        ]
      }
    ]
  }
}

方案三：VS Code 扩展

melon-hub/claude-code-image-paste-wsl：在 VS Code 集成终端中按 Ctrl+Alt+V，通过 PowerShell 抓图保存并插入路径。

适合在 VS Code 里用 Claude Code 的用户。

方案四：手动路径法（最简但最麻烦）

截图保存到固定目录，手动输入路径。无需任何额外工具。

实操记录

环境：

• Windows 11 + WSL2
• RTX 4070 / NCASE M1
• Claude Code 2.1.143
• Windows Terminal

安装 wsl-screenshot-cli：

curl -fsSL https://nailu.dev/wscli/install.sh | bash
# 安装到 ~/.local/bin/wsl-screenshot-cli, v1.3.1

配置 Claude Code Hooks：编辑 ~/.claude/settings.json 添加 SessionStart/SessionEnd hooks。

验证结果：微信截图 → Ctrl+Shift+V → 路径成功粘入 Claude Code → 图片正常读取。✅

关键结论

1. 这是 WSL 架构限制 + Claude Code 实现缺陷 的叠加问题，不是单一 bug
2. 官方修复进度缓慢（#50552 从 2026-04 至今未修）
3. 所有可靠方案的本质都是：用 Windows 侧 PowerShell 抓图 → 存文件 → 粘贴路径
4. wsl-screenshot-cli 是当前最成熟的方案，daemon 模式对系统资源影响可忽略

关联页面

• Claude Code