我最近在 Ubuntu 上折腾终端环境时，也撞上过这个很“经典”的问题：从浏览器复制一段多行命令，切回 Zsh 准备粘贴，结果屏幕没有出现预期的命令，反而在最前面冒出一行^[[200~，末尾还跟着一个孤零零的~，命令行被搅得没法看。第一反应是 Zsh 出 bug 了，后来才发现，祸根不在 Zsh，而在终端模拟器和 shell 之间一套名为“bracketed paste（括号粘贴）”的协议。这篇文章就来扒一扒^[[200~和~到底是谁发出来的、为什么有的环境出现有的环境不出现，以及不同场景下该怎么处理。看完之后，你不仅能解决这个乱码，还能顺手搞清楚 tmux、SSH 里粘贴异常的一部分根因。
1. 不是 Zsh 的锅：^[[200~是终端自带的“粘贴保险丝”
1.1 三条控制序列和一次粘贴的完整旅程
要理解这个乱码，得先搞清楚现代终端模拟器和 shell 之间的一层隐晦约定。当你从浏览器、编辑器或 PDF 里复制一段文本，再回到终端按中键或Ctrl+Shift+V时，终端模拟器并不是简单地把文本“敲”进去，而是会先做一件事：向当前处于前台的应用（比如 Zsh）发送一段 ESC 控制序列。
这段序列通常是ESC[200~，也就是屏幕上显示出来的^[[200~。它的作用是告诉 Zsh：“下面我要粘贴一段内容了，这段内容是批量粘贴，不是用户逐字输入的，请你把它当作一整块文字处理。”接着，终端才把剪贴板里的真实内容原样发送出去。全部发送完成后，终端还会再补一段ESC[201~，表示“粘贴结束，你可以恢复正常的行编辑处理了”。
为什么需要这套“保险丝”？因为如果不加标记，粘贴多行命令时会产生两个问题。一是换行符会被立即执行，比如你粘贴一段 for 循环，刚粘到第一行带回车的地方，命令就跑了，后面的内容全成了噪声。二是某些特殊字符会被行编辑器误解，比如粘贴内容里的#可能被当成注释起始、\可能被当成续行符、反斜杠被吞掉等。有了200~和201~这对“括号”，Zsh 就知道：“这是一次整体粘贴，换行我先不执行，特殊字符我也不解析，等全部内容落地后再说。”
这就是 bracketed paste 机制的核心。终端是否使用这套协议，通常由一个名为“DEC 私用模式 2004”的开关控制：ESC[?2004h开启，ESC[?2004l关闭。现代终端模拟器默认开启，shell 端（Zsh 5.1 以后、Bash 4.4 以后）也默认支持。正常情况下你不会看到任何标记，因为协议双方都心照不宣，终端发的开始标记和结束标记会被 shell 的编辑组件悄悄“吃掉”。
1.2 为什么屏幕上看起来是^[[200~和~
屏幕上的乱码看起来像两串字符，其实本质是两个 ESC 控制序列没有被人吃掉。^[是 ESC 键在cat -v风格下的显示方式，并不是你按住 Shift+6 打出来的“^”和“[”。所以^[[200~实际是ESC [ 200 ~这四样东西：ESC 字符、左中括号、数字 200、波浪号。
末尾那个孤零零的~其实就是结束标记ESC[201~的最后一部分。因为^[[201~会被终端显示为^[加上[201~，其中[201~的最后一个字符依然是波浪号，所以在视觉上你就看到了一个“尾巴”。某些情况下，由于光标换行或命令行长度问题，开始标记只显示了一部分，结束标记只看到最后的~，于是就成了标题里那种“前面^[[200~，后面~”的诡异组合。
想亲眼确认这一点，可以在 Zsh 里执行一个很简单的命令：
cat -v然后粘贴一段文本。如果粘贴协议没有被正确消费，你会看到类似：
^[[200~some text here^[[201~cat -v会把 ESC 直接显示成^[，后面的[200~、[201~按原样输出。这样一来，你就能分清哪些字符是粘贴的真实内容，哪些是控制序列残留了。
1.3 谁负责吃掉标记：Zsh 行编辑器的内置 widget
Zsh 从 5.1 版本开始，在行编辑器 zle 里内置了名为bracketed-paste的 widget。当终端发出ESC[200~时，zle 会捕获这个序列，进入“粘贴模式”，把接下来收到的内容原样插入缓冲区，换行先挂起不执行，直到匹配到ESC[201~再恢复常态。
判断你的 Zsh 是否注册了这个 widget，可以在 Zsh 里执行：
zle -l | grep bracketed正常情况会看到bracketed-paste这一项。如果输出为空，或者显示undefined widget，那就说明这个能力没有挂上。还有一种情况：widget 虽然存在，但已经被某个插件覆盖成了别的函数，比如某些提供“粘贴时自动给 URL 加引号”的插件会把bracketed-paste替换成自定义版本。这类替代实现如果没处理好 200 和 201 的配对，就很容易在屏幕上留下标记残留。
理解了这套机制之后，下面就能按“终端发的 → zsh 接的 → 中间环节是否转歪了”这条思路来排查了。
2. 三步定位：用空环境和原始终端协议复现问题
2.1 用env -i zsh -f甩开.zshrc的干扰
遇到粘贴乱码，第一件事不是急着改配置，而是先确定问题出在用户配置层还是基础环境层。最有效的隔离方法是用一个不带任何配置的 Zsh 来复现：
env -i zsh -fenv -i会清空当前环境变量，zsh -f会让 Zsh 不读取.zshrc、.zprofile等任何启动文件。在这个极简 shell 里再粘贴同一段内容，如果乱码消失，说明问题基本锁定在你的.zshrc、zsh-autosuggestions、zsh-syntax-highlighting或 oh-my-zsh 插件配置上。如果极简 shell 里依然出现^[[200~，那说明问题更底层，可能出在终端模拟器本身、SSH 转发、tmux 或者 Zsh 版本上。
这一步非常关键。很多人在社区里搜到“解决方案”就直接往.zshrc里塞，结果问题依旧，就是因为没先做隔离测试。隔离结果会直接决定你下一步该往哪个方向查。
2.2 手动开启 / 关闭 2004 模式判断终端有没有在发
确认完 Zsh 配置层之后，下一步需要确认终端到底有没有在发送 bracketed paste 序列。手动开关这个模式非常容易：
# 关闭 bracketed paste 模式 printf '\e[?2004l' # 开启 bracketed paste 模式 printf '\e[?2004h'先在终端里执行关闭命令，然后粘贴。如果关闭之后^[[200~和^[[201~就消失了，说明你的终端模拟器确实启用了这套协议，只是 zle 端没有正确消费。接着再执行开启命令，恢复原状。
这里有一个容易踩的坑：不少人用echo来发这段序列，但echo在某些发行版默认不会解释\e，而是把反斜杠字母原样输出。最好用printf，它会正确地把\e转成 ESC 字符。执行之后屏幕可能不会有任何反应，这是正常的，控制序列本来就不产生可见输出。
如果你关掉 2004 模式后，粘贴内容不再出现标记，但多行内容依然被逐行执行、特殊字符依旧被错误解析，那说明终端和 Zsh 之间的 bracket 流程整个没连通。这种情况下面再谈 tmux 和 SSH 的干扰。
2.3 检查 zle、terminfo 与 Zsh 版本的匹配情况
第三步是把三个关键点并列检查：Zsh 版本、zle widget 状态、terminfo 能力。命令分别如下：
zsh --version zle -l | grep bracketed infocmp $TERM | grep -i bracketedZsh 5.1 以下对 bracketed paste 的支持不完整，如果 Ubuntu 仓库里的版本太老，建议优先升级 Zsh。Ubuntu 22.04 自带的 Zsh 是 5.8.1，Ubuntu 20.04 自带 5.8，都是支持完整的。
zle -l | grep bracketed看的是 zle 有没有注册这个 widget。没有的话，待会在第 4 节里给出恢复方法。
infocmp $TERM | grep -i bracketed看的是当前TERM对应的 terminfo 数据库里是否声明了bracketed_paste能力。如果这个能力不存在，终端模拟器或者 ssh 会话时的 terminfo 可能根本不通知 Zsh 开启协议，这样反而不会出现^[[200~标记乱码，但也可能造成其他粘贴问题。你只需要知道：这一步能帮你判断当前会话中“终端认为自己在用什么方式工作”。
3. 三个高频现场：本地终端、tmux、SSH 的差异
3.1 本地粘贴：大多数是“终端发了协议，zsh 没接住”
在本地 Ubuntu 桌面环境下，最常见的乱码场景是：终端模拟器正常发送ESC[200~，但 Zsh 的 zle 端没有匹配的 widget 去处理，于是控制序列被当作普通字符插入命令行。
为什么 zle 会“没接住”？多数情况是配置层有意或无意覆盖了默认行为。比如某些用户为了支持“粘贴 URL 自动加引号”，装了自定义的bracketed-paste函数；又比如一些较老的插件会在启动时调用zle -N bracketed-paste some-plugin-widget，把原有 widget 顶掉。替换后的实现一旦没处理结束标记，残留就出现了。
还有一种比较隐蔽的情况：.zshrc里手动设置了zle_bracketed_paste数组。Zsh 内部会用这个数组保存开始标记和结束标记的序列值，默认是：
$'\e[200~' $'\e[201~'如果你在某个配置片段中把它写成了空数组或者只留下一个值，zle 就不知道如何匹配结束序列，粘贴内容的尾部就可能直接把^[[201~暴露在命令行上。
3.2 tmux 内粘贴：双保险为什么变成双乱码
在 tmux 里出现问题，排查链路会比本地复杂一层，因为 tmux 本身也是一个“终端应用”。你的外层终端模拟器把剪贴板内容交给 tmux，tmux 再把它转发给当前 pane 里运行的前台进程（比如 Zsh）。这意味着 bracketed paste 协议可能被两层分别处理。
如果 tmux 内部出现^[[200~标记残留，一般不是 tmux 主动生成的，而是转发链路中出现了“错位”。常见原因有几种：一是 tmux 版本过老，对 bracketed paste 的转发支持不完整；二是当前 pane 内的 Zsh 启动较慢，tmux 已经把内容送进去时 zle 还没完成初始化，标记被输出到了未就绪的 shell 上；三是你在 tmux 里手动设置了某些allow-passthrough相关选项，导致原本该被 tmux 吃掉的控制序列变成透明转发。
还原 Tmux 场景时，先在 tmux 外层跑一次env -i zsh -f，再在 tmux pane 里跑一次同样的测试。如果 tmux 内部出现双份标记，比如连续看到两组^[[200~，那基本可以判断是“双层协议叠加”。优先升级 tmux 到 3.x 版本，并保持 pane 内的TERM为screen-256color或tmux-256color这类 tmux 专门提供的值，而不是笼统的xterm-256color。
3.3 SSH 远端粘贴：TERM 环境先把协议拦在半路
SSH 到远端服务器时，你本地的终端模拟器发送的控制序列会先经过 ssh 进程，再到达远端伪终端（pty）。这个过程不会主动修改 200 和 201 的标记内容，但远端会话的TERM环境变量会影响 Zsh 是否愿意开启 bracketed paste 能力。
典型的问题出现在：本地明明一切正常，SSH 到某台服务器后粘贴却出现^[[200~。这种情况优先检查远端的TERM：
echo $TERM如果输出是dumb、linux或者某种没有声明bracketed_paste能力的 terminfo，Zsh 会默认不进入粘贴协议处理流程，终端发来的标记就有概率被直接显示出来。合理的设置是把远端交互式会话的TERM设为xterm-256color，在 tmux 里则设为tmux-256color或screen-256color。
在远端同样可以跑infocmp $TERM | grep -i bracketed，如果输出里有bracketed_paste能力，说明 terminfo 层面是支持的。如果完全没有输出，问题就找到了。
4. 修复方案：从临时止血到配置根治
4.1 临时开关：printf '\e[?2004l'先让屏幕干净
如果乱码已经出现，想立刻让当前终端恢复可用的命令行，最快的方法是直接在当前会话里关闭终端侧括号粘贴协议：
printf '\e[?2004l'执行之后，终端模拟器就不会再给 Zsh 发送ESC[200~和ESC[201~标记了，粘贴内容会退回“盲贴”模式。代价是：多行粘贴内容的换行会被逐行执行，特殊字符也可能被行编辑器错误解析。因此这个命令只适合应急，不建议写进.zshrc让它永久生效。
如果你不想每次手动敲，可以在~/.zshrc里加一个别名：
alias paste-off="printf '\e[?2004l'" alias paste-on="printf '\e[?2004h'"这样遇到突发乱码，敲paste-off就能快速止血。不过这只是让“眼不见心不烦”，并没有真正让 Zsh 学会消费协议，下一小节才是根治手段。
4.2 恢复 zle 默认 widget，重新接住 200~ 标记
针对“本地终端 + Zsh 配置层覆盖”这种情况，最治本的办法是把 zle 的bracketed-pastewidget 恢复成默认状态。在你的~/.zshrc中加入或修正以下内容：
# 恢复 zsh 内置的 bracketed-paste widget autoload -Uz bracketed-paste 2>/dev/null zle -N bracketed-paste bracketed-paste然后重新加载配置。如果使用 oh-my-zsh，建议在.zshrc的插件列表之后加这段，确保它在其他插件之后执行：
source ~/.zshrc加载后再执行一次检查：
zle -lL bracketed-paste正常会显示类似bracketed-paste: bracketed-paste的结果，表示 widget 已经挂到对应的函数上。如果显示undefined widget或no such widget，说明函数文件还没找到，多半是$fpath或$FPATH没包含 Zsh 内置函数目录，这种情况直接升级 Zsh 通常更快。
还有一个需要检查的变量是zle_bracketed_paste。如果之前配置里动过它，可以恢复默认：
typeset -ga zle_bracketed_paste zle_bracketed_paste=( $'\e[200~' $'\e[201~' )如果你用的是带“粘贴时自动给 URL 加引号”这类增强插件，而且这个插件确实是自己写的，那最好保留插件的功能，但要确保替换后的 widget 完整处理了开始标记和结束标记。最简单的判断标准还是：env -i zsh -f下粘贴干净，正常配置下粘贴就脏，那一定是你配置里某个环节的问题。
4.3 保守方案：让终端干脆别发协议
如果你排查了一圈，确实不想折腾插件兼容，也不想升级 Zsh，那你还有一个“所有环节都不怎么出错”的保守策略：在终端模拟器设置里关闭 bracketed paste 支持。
不同终端模拟器的设置项名称不太一样，有的叫“Bracketed paste mode”，有的叫“启用括号粘贴”，还有的是在“高级”设置里的“允许应用程序使用转义序列”。关闭之后，终端模拟器在粘贴时不会发送200~标记，Zsh 也不会收到这一串控制序列。这个方案能直接消除^[[200~乱码，代价同样是要接受“多行粘贴会逐行执行”等老式行为。
需要注意，很多终端模拟器默认并不提供一个简单开关给用户，终端模拟器只会在应用（Zsh）声明支持时才启用 2004 模式。如果终端不管三七二十一，不管应用支不支持都发标记，问题就会从“Zsh 不吃标记”变成“终端乱发标记”。这类情况可以通过修改应用的 terminfo 能力来“哄住”终端，属于比较 hack 的做法，一般用不上，提一下即可。
我的建议优先级永远是这样：先恢复 zle 默认 widget，再排查第三方插件，最后才用“关闭 2004 模式”这个一刀切手段。因为 bracketed paste 在现代 shell 里是有实际价值的，牺牲它对日常多行粘贴体验影响很大。
4.4 tmux 与 SSH 场景下的定向处理
tmux 场景下的处理，核心是让 tmux 知道底层终端能做什么。老版本 tmux 对 bracketed paste 的传递支持不完整，升级到 3.x 之后，大多数转发问题会消失。配置 tmux 时建议保留默认的terminfo能力，不要随意在.tmux.conf里写terminal-overrides去覆盖bracketed_paste相关项。除非你明确知道某个覆盖表达式做了什么，否则这种全局 override 经常是乱码的源头。
SSH 场景下的处理，核心是让远端会话的TERM与真实终端能力匹配。如果不确定，可以在远端.zshrc最前面加一个兜底：
if [[ "$TERM" == "dumb" || -z "$TERM" ]]; then export TERM=xterm-256color fi但这个兜底只解决“TERM 丢失”的问题。如果远端.zshrc里有其他插件覆盖了 zle widget，同样要执行上文的恢复操作，这就和本地终端场景殊途同归了。
5. 和粘贴乱码一起出现的“姊妹问题”
5.1 中文变成%编码，别和括号粘贴混为一谈
很多人搜索“粘贴乱码”时，会把^[[200~和“中文粘贴成%E4%B8%AD这种百分号编码”混在一起。其实这是两码事，解决思路完全不同。
%E4%B8%AD这类现象，通常是 Zsh 把粘贴内容当成了需要 URL 编码的文本，和 bracketed paste 的一对标记关系不大。排查的时候先看系统 locale：
locale如果LANG不是类似en_US.UTF-8或zh_CN.UTF-8的 UTF-8 值，就可能出现中文粘贴乱码或输入法异常。在/etc/locale.conf或.zshrc里导出正确的LANG通常就能解决。还有一种情况是 Zsh 的magic_equal_subst选项对=和 URL 相关字符做了特殊处理，粘贴含 URL 参数的中文文本时，=后面的字符串会被当路径展开。遇到这种情况，可以先临时unsetopt magic_equal_subst再粘贴，确认是不是它导致的。
5.2 粘贴时 Zsh 卡死或高亮崩掉
比乱码更恼人的是：粘贴大段内容时 Zsh 转圈卡住，或者语法高亮把内容染得乱七八糟。这和^[[200~是同源的衍生问题——终端告诉 Zsh“这是一次批量粘贴”，但zsh-syntax-highlighting插件却按逐字输入的方式对整段内容做高亮解析，几百行文本一次性进来，开销自然上涨。
处理思路有两步。第一步，更新插件到最新版本，新版zsh-syntax-highlighting对多行粘贴做了不少优化。第二步，如果更新后还卡，可以在粘贴前手动暂停高亮，粘贴完再恢复。很多插件提供了开关，比如zsh-syntax-highlighting可以通过ZSH_HIGHLIGHT_MAX_BUFFER_SIZE限制大缓冲区高亮，超过这个长度的内容不做高亮。你可以按实际使用习惯调整这个值，比如：
ZSH_HIGHLIGHT_MAX_BUFFER_SIZE=2048这不会直接解决^[[200~乱码，但能避免“乱码没看到，先被卡顿逼疯”的次生体验问题。
5.3 我留下的检查习惯和小工具
踩过几次坑之后，我给自己留了一套固定检查顺序，遇到任何终端粘贴异常，基本按这个顺序走能快速定位：
- 在问题环境里执行
env -i zsh -f，用空 shell 粘贴同一内容，确认是全局问题还是配置问题。 - 执行
zle -l | grep bracketed，确认 zle 是否注册了bracketed-pastewidget。 - 执行
printf '\e[?2004l'，关闭协议后粘贴，确认标记是不是来自终端侧。 - 用
infocmp $TERM | grep -i bracketed确认 terminfo 能力是否正常。 - 最后再动
.zshrc，改完用exec zsh -l重启会话验证。
另外我还会在.zshrc里留一个调试函数，方便随时看状态：
paste-debug() { echo "-- zle widget --" zle -l | grep bracket echo "-- zle_bracketed_paste --" print -r -- "${(q)zle_bracketed_paste[@]}" echo "-- terminfo --" infocmp "$TERM" 2>/dev/null | grep -i bracketed }这个函数本身不解决问题，但能让我在排查时少敲几行命令。实际用下来，大多数^[[200~乱码都卡在同一个位置：Zsh 的 widget 被插件覆盖。所以如果你时间紧，可以跳过一堆测试，直接检查.zshrc里有没有哪个插件碰过bracketed-paste。把这个覆盖关系理顺，屏幕干净只是时间问题。
