# Claude Code 怎么粘贴图片：Mac 按 Ctrl+V，Windows 按 Alt+V

> 终端里的 Claude Code 粘贴图片：Mac 和 Linux 按 Ctrl+V（Control 键），Windows 和 WSL 按 Alt+V。粘不进去就拖入文件或写路径。

- URL: https://blog.laozhang.ai/zh/posts/claude-code-paste-image
- Published: 2026-10-02
- Updated: 2026-10-02
- Author: LaoZhang AI Team (https://blog.laozhang.ai/zh/about)
- Category: Claude Code
- Tags: Claude Code, 粘贴图片, 截图, 快捷键, WSL, VS Code

---
在终端里运行的 Claude Code，粘贴图片用的不是系统粘贴键。macOS 和 Linux 按 `Ctrl+V`，Mac 上按的是 Control 键，不是 Command 键；Windows 和 WSL 按 `Alt+V`。只有 iTerm2 被官方点名可以直接用 `Cmd+V`。图片进去以后，光标位置会出现一个 `[Image #1]` 这样的占位标记，看到它再发送。

按了没反应，或者看到 `No image found in clipboard`，先不必和剪贴板较劲：把图片文件拖进 Claude Code 窗口，或者在提示里直接写上文件路径，这两种办法在哪种环境下都不经过剪贴板。

先交代依据。下面的快捷键和修复记录出自截至 2026 年 10 月 2 日的 Anthropic 官方文档和 Claude Code 更新日志（当时最新一条是 2.1.287），没有在各个终端里逐一按过。实际走过的只有一条：在 macOS 的 Claude Code 桌面版里给出图片路径，Claude 打开了一张 1416×1366 的 PNG 和一张 2000×1125 的 WebP，并描述了画面内容。所以每个按键后面都标了出处，方便你对照自己的版本。

## 粘贴图片按哪个键：按终端、扩展、桌面版分开看

决定按键的是两件事：Claude Code 跑在哪里（终端、VS Code 扩展面板、桌面版），以及操作系统。终端里用 Claude Code 自己的快捷键；带输入框的图形界面用平常的粘贴或附件按钮。

![Claude Code 粘贴图片按键对照：macOS 终端和 Linux 终端按 Ctrl+V，Windows 与 WSL 按 Alt+V，SSH 远程会话改用 scp 传文件再写路径，VS Code 扩展面板和桌面版用平常的粘贴键或附件按钮](https://blog.laozhang.ai/posts/zh/claude-code-paste-image/img/paste-image-keys.webp)

| 你的环境 | 怎么把图片放进去 | 出处与注意 |
| --- | --- | --- |
| macOS，任意终端 | `Ctrl+V`（Control 键） | [交互模式文档](https://code.claude.com/docs/en/interactive-mode)的快捷键表 |
| macOS，iTerm2 | `Ctrl+V` 或 `Cmd+V` | 同上；`Cmd+V` 从 2.1.0 起支持，文档只点名了 iTerm2 |
| Windows 原生终端 | `Alt+V` | 同上；1.0.93 加入 |
| WSL | `Alt+V`，`Ctrl+V` 也绑定了 | 文档建议终端截走 `Ctrl+V` 时改用 `Alt+V` |
| Linux | `Ctrl+V` | 读取剪贴板要靠 xclip，Wayland 下回退到 wl-paste（据更新日志 2.0.52 的措辞推断） |
| SSH 等远程会话 | 快捷键读不到你本机的剪贴板 | 用 scp 把文件传过去，再写路径 |
| VS Code 扩展面板 | 在输入框里按平常的粘贴键；文件按住 Shift 拖入 | [VS Code 文档](https://code.claude.com/docs/en/vs-code) |
| VS Code 集成终端 | 与同系统的终端相同 | 集成终端里跑的是命令行版本 |
| 桌面版 | 附件按钮，或把文件拖进输入框 | [桌面版文档](https://code.claude.com/docs/en/desktop) |
| 任何环境 | 拖入文件，或写文件路径 | [常见工作流文档](https://code.claude.com/docs/en/common-workflows)的「Work with images」 |

官方文档在快捷键表下面有一句提醒：快捷键可能因平台和终端而不同。除了 iTerm2，Ghostty、Kitty、WezTerm、Warp、系统自带的终端、Windows Terminal、cmd、PowerShell 各自的表现，公开文档里没有逐个记载。表里的键在你的终端上不起作用时，直接用最后一行的办法。

如果想换一个键，这个动作在快捷键配置里叫 `chat:imagePaste`，可以重新绑定，配置文件的写法见[官方 keybindings 文档](https://code.claude.com/docs/en/keybindings)。

## 为什么 Mac 上是 Ctrl+V 不是 Cmd+V：终端的粘贴键只送文字

因为 `Cmd+V` 是终端自己的粘贴键，它做的事是把剪贴板里的文字当作键盘输入送给正在运行的程序。剪贴板里是一张图片时，没有文字可送，终端什么也不会发，Claude Code 根本不知道你按过键。

`Ctrl+V` 则是 Claude Code 自己绑定的按键：程序收到它之后，自己去读系统剪贴板，取出图片数据。所以它和系统粘贴键必然不是同一个键。Windows 上用 `Alt+V` 也是同样的原因，许多 Windows 终端把 `Ctrl+V` 留给了文字粘贴，按键到不了 Claude Code。

这段是对机制的解释，不是 Anthropic 的原话，但它和官方的安排对得上：2.1.0 的更新日志写的是「在 iTerm2 中增加 Cmd+V 粘贴图片的支持（映射到 Ctrl+V）」，也就是说 `Cmd+V` 能用，靠的是专门为 iTerm2 做的一层转换。

记住这一点，换终端、换系统时就不用再查：粘贴文字用终端的键，粘贴图片用 Claude Code 的键。

## 怎么确认图片粘进去了：光标处出现 Image #N 标记

看输入框。粘贴成功后，光标位置会插入 `[Image #1]` 这样的标记，官方文档把它叫作 chip（中文文档译为「芯片」）。再贴一张就是 `[Image #2]`，依此类推。

这个标记有两个用处：

- **按位置指代**：标记插在光标处，你可以在一句话里写「按 `[Image #1]` 的布局，改成 `[Image #2]` 的配色」，让 Claude 分清哪张是哪张。同一段对话里可以用多张图片。
- **回头打开原图**：Claude 在回复里提到 `[Image #1]` 时，Mac 上按住 Cmd 点击、Windows 和 Linux 上按住 Ctrl 点击，可以用默认看图软件打开它。

另外，2.1.132 之后，按下 `Ctrl+V` 到图片读取完成之间，底部会显示「Pasting…」提示。提示出现又消失、输入框里却没有标记，说明按键到了 Claude Code，但剪贴板里没读到图片，问题出在剪贴板一侧而不是按键。

位置标记是 2.1.83 才有的，同一版起 Claude 还能拿到粘贴图片在磁盘上的路径，用于文件操作；2.1.275 起，粘贴和附加的图片保存在 Claude 无需权限确认就能打开的位置，桌面版和 VS Code 也一样。版本更早的话，成功粘贴后的样子会和上面描述的不同。

## 无法粘贴或提示 No image found in clipboard：按顺序查五件事

失败的原因基本落在五处，按排查成本从低到高查。

![Claude Code 图片粘贴失败的五步排查：按键是否正确、剪贴板里是不是图片、按键是否被终端截走、是否在远程会话、版本是否太旧，都不行就拖入文件或写文件路径](https://blog.laozhang.ai/posts/zh/claude-code-paste-image/img/paste-image-troubleshooting.webp)

**第一，按的是不是对的键。** Mac 上是 Control 而不是 Command；Windows 和 WSL 是 `Alt+V`。完全没有反应、连「Pasting…」都不出现，多半是这一步。

**第二，剪贴板里是不是图片。** 截图要截到剪贴板，而不是存成文件：

- macOS：`Cmd+Shift+4` 默认把截图存成文件，再加按 Control（`Cmd+Ctrl+Shift+4`）才是复制到剪贴板。
- Windows：`Win+Shift+S` 截取后直接进剪贴板。

已经存成文件的截图不用重截，把文件拖进窗口即可。第三方截图工具各自往剪贴板里放什么格式，没有统一的说法。博客园 2026 年 4 月有一篇排查记录提到，Windows 11 的 cmd 里按 `Alt+V` 贴不进 Snipaste 的截图、提示 `No image found in clipboard`，换到 PowerShell 就正常。这是一位作者的个例，可以作为换终端试一次的理由，不能当成规律。

**第三，按键有没有被终端截走。** WSL 上 `Ctrl+V` 和 `Alt+V` 都绑定了，终端把 `Ctrl+V` 拿去粘贴文字时，改按 `Alt+V`。在 GitHub 的相关讨论里，也有人对 Windows 用户给出同样的回答：`Ctrl+V` 常被终端拦下，按 `Alt+V`。别的终端如果把这两个键都占了，就到 keybindings 里把 `chat:imagePaste` 换成一个没被占用的键。

**第四，是不是在远程会话里。** 通过 SSH 连到另一台机器时，Claude Code 运行在远端，它读的是远端的剪贴板，够不到你面前这台电脑上的截图。处理办法见下一节。

**第五，版本是不是太旧。** 不少「找不到图片」其实是已经修掉的 bug，先升级到最新版再试是合理的一步。对照下面的表，看你的症状有没有对应的修复。

| 症状 | 修复版本 | 更新日志的说法 |
| --- | --- | --- |
| Wayland 下无法粘贴图片 | 2.0.52 | 没有 xclip 时回退到 wl-paste |
| WSL2 里贴不进 Windows 剪贴板中的图片 | 2.1.136 | xclip 和 wl-paste 读不到图片数据时，改走 PowerShell |
| Windows 上剪贴板里明明是截图，`Alt+V` 却报找不到图片 | 2.1.141 | 已修复 |
| WSL 的 `Alt+V` 失效、Windows 11 截图贴不进去 | 2.1.157 | 已修复，并支持从资源管理器拖入图片 |
| 剪贴板里是文字时，`Ctrl+V` 不粘贴文字反而报 No image found in clipboard | 2.1.181 | 已修复 |
| Alpine 等 musl 环境下粘贴图片不可用 | 2.1.239 | 原生的图片粘贴组件可以加载了 |
| VS Code 在 WSL2 里粘贴截图，输入框里出现一串乱码字节 | 2.1.267 | 剪贴板提供图片时作为附件加入，否则忽略这次粘贴 |

以上条目均来自 [Claude Code 更新日志](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md)。Linux 上还有一点要留意：从 2.0.52 和 2.1.136 的措辞看，粘贴依赖 xclip 或 wl-paste 这类剪贴板工具来读取图片，系统里一个都没有时，快捷键自然读不到东西。官方没有给出一份依赖清单，这是根据发布说明作出的推断。

五项都查过还是不行，就不要再试快捷键了，用下面两种不经过剪贴板的办法。

## SSH 远程会话里粘贴不了：用 scp 传文件，再写路径

远程会话里不要指望快捷键，把图片文件传到远端，再告诉 Claude 路径。这也是 Anthropic 自己给的方向：2.1.2 把通过 SSH 粘贴图片时的报错改成了建议使用 scp，不再提示那个在远程用不上的快捷键。

在本机另开一个终端，把截图传过去：

```bash
scp ./error-screenshot.png dev@build-server:/home/dev/shots/
```

用户名、主机名和目录换成你自己的。然后在远端的 Claude Code 里写：

```text
看一下 /home/dev/shots/error-screenshot.png 这张报错截图，问题出在哪里？
```

tmux 里粘贴图片的表现，官方文档没有记载。在 tmux 里按键无效时，同样用路径。

## 不经过剪贴板的两种办法：拖入文件，或直接写图片路径

这两种办法是官方「Work with images」里和粘贴并列的另外两条，任何环境都适用，也是粘贴失败时最省事的出路。

**拖入文件。** 把图片文件从访达或资源管理器拖进 Claude Code 窗口。2.1.2 起，拖进终端的图片会带上来源路径；WSL 从 2.1.157 起支持从 Windows 资源管理器拖入。

**写路径。** 在提示里直接给出文件位置，官方的示例是：

```text
Analyze this image: /path/to/your/image.png
```

Claude 会用读文件的工具打开它。这一条在 macOS 桌面版里走过：给出一张 1416×1366 的 PNG 和一张 2000×1125 的 WebP 的路径，Claude 都读出了内容并作了描述。它不依赖终端类型、剪贴板工具或按键绑定，远程会话里也照样能用，缺点只是要先把图片存成文件。

图片进去之后怎么问，官方给的几个例子可以直接照着用：这张图里是什么；这是报错截图，原因是什么；按这张设计稿生成对应的 CSS。

## VS Code 扩展和桌面版：输入框里用平常的粘贴键或附件按钮

图形界面里不需要记特殊按键。

VS Code 要先分清你用的是哪一种。在扩展的面板里，把图片从剪贴板粘贴到输入框就会成为附件，用的就是系统平常的粘贴键；要附加文件，按住 Shift 再把文件拖进输入框；想把某个附件移出上下文，点它上面的 X。如果你是在 VS Code 的集成终端里输入 `claude` 启动的，那是命令行版本，按键规则和前面表里同系统的终端一样。两种用法各自走哪个账号，见 [Claude Code 在 VS Code 里怎么查看账号](https://blog.laozhang.ai/zh/posts/check-claude-code-vscode-account)。

桌面版的 Code 标签页里，用输入框旁边的附件按钮添加图片、PDF 等文件，或者把文件直接拖进输入框。桌面版文档没有专门提到从剪贴板粘贴，稳妥的做法是用附件按钮或拖放。

## 图片大小和格式有没有限制：官方文档没有给出数字

截至 2026 年 10 月 2 日，交互模式、常见工作流、VS Code 和桌面版这几页文档都没有写粘贴图片的最大体积，也没有列出接受的格式。能确定的是更新日志里的几条处理方式：

- 2.1.0 修复了粘贴大图时报「Image was too large」的问题，并加入 TIFF 格式支持，提高了 macOS 截图粘贴的成功率。
- 2.1.97 起，粘贴和附加的图片会被压缩到与 Read 工具读取图片相同的 token 预算。
- 2.1.126 修复了粘贴超过 2000px 的图片导致会话出错的问题，此后图片在粘贴时会被缩小。
- 2.1.157 起，零字节或损坏的图片不再让请求崩溃，而是变成一段文字占位。

2000px 是官方提到的唯一一个像素数字，它描述的是一个已修复的 bug，不是一条写明的上限。实际含义是：新版本里大截图会被自动缩小，一般不需要自己先压缩；但整屏截图缩小以后小字可能看不清，要让 Claude 读报错文字或界面细节时，只截相关区域效果更可靠。一张图片占多少 token，官方文档同样没有给出数字。

粘贴图片是把图交给 Claude 看。反过来想让 Claude Code 产出图片，是另一件事，做法见 [Claude Code 怎么生成图片：代码渲染还是调图像模型，怎么选](https://blog.laozhang.ai/zh/posts/claude-code-image-generation)。