zsh Tab 补全卡住排查：iTerm2 tmux Control Mode 与 fzf-tab popup 冲突

第一层问题：让 zsh 补全忽略大小写#

zsh 的大小写不敏感补全可以通过 matcher-list 实现。把下面这行放在 compinit 之后即可让所有 completion 生效，包括 cd、git 等命令：

1
zstyle ':completion:*' matcher-list 'm:{a-zA-Z}={A-Za-z}'

这行配置只改变“候选如何匹配”，不会改变候选列表如何展示。比如目录名是 Projects，输入 cd pro<Tab> 时，zsh 可以把 pro 和 Pro 当成同一类字符去匹配。

如果 dotfiles 由 chezmoi 管理，最好不要直接改生成后的 ~/.zshrc，而是改 chezmoi 里的源文件，再只针对 ~/.zshrc 做一次定向 apply。这样下次同步配置时不会被源文件覆盖，也不会误触碰其他还没准备同步的 dotfiles。

完成后可以用两个动作验证：

1
zsh -n ~/.zshrc
2
zstyle -a ':completion:*' matcher-list matcher_list
3
print -l $matcher_list

能看到 m:{a-zA-Z}={A-Za-z}，就说明新 shell 会加载这条 matcher 配置。

第二层问题：远程 Tab 补全为什么像卡住#

后续问题发生在另一个链路里：iTerm2 通过 SSH 进入远端主机，并自动进入 tmux Control Mode。这个模式通常类似：

1
RemoteCommand tmux -u -CC new-session -A -D -X -s <session-name>

为了避免泄露环境细节，这里省略真实主机名、IP、用户名和会话名。关键点不是远端是哪台机器，而是 tmux -CC：这是 iTerm2 的 tmux Control Mode，终端窗口、pane、tab 等 UI 由 iTerm2 和 tmux 的控制协议共同管理。

当时远端 zsh 的 fzf-tab 后端仍然配置为：

1
zstyle ':fzf-tab:*' fzf-command ftb-tmux-popup

ftb-tmux-popup 的思路是在 tmux 里再开一个 popup，把 fzf 候选列表放进去。普通 tmux 里这很好用，但在 iTerm2 的 Control Mode 里，外层本来就不是传统意义上的 tmux 终端绘制模式。补全过程里再调用 tmux popup，就可能卡在 popup 创建、控制序列或交互输入输出上。

最终表现就是：按 Tab 之后没有候选弹窗，shell 也不再给出明显反馈，看起来像远端终端卡住。

诊断思路#

这类问题容易误判成“刚才加的大小写 matcher 把补全搞坏了”。实际排查时要把两个层次拆开：

1. matcher-list 只决定候选匹配规则。
2. fzf-tab 的 fzf-command 决定候选列表如何展示。
3. tmux -CC 改变了终端 UI 的承载方式。

可以先在远端 shell 里确认当前 fzf-tab 后端：

1
zstyle -s ':fzf-tab:*' fzf-command fzf_tab_command
2
print -r -- $fzf_tab_command

如果输出是 ftb-tmux-popup，说明补全候选会尝试走 tmux popup。

再确认当前 tmux 客户端是否处于 Control Mode：

1
tmux display-message -p 'control=#{client_control_mode}'

当结果是 control=1 时，就说明当前客户端是 Control Mode。这个状态下继续强制使用 ftb-tmux-popup，就是这次问题的核心组合。

为了排除 tmux 本身不支持 popup，也可以检查 tmux 版本和 popup 能力。但这次的结论不是“tmux popup 不可用”，而是“在 iTerm2 Control Mode 这个客户端形态下，不适合让 fzf-tab 再走 tmux popup 后端”。

修复方式：Control Mode 下退回普通 fzf#

最小修复不是禁用 fzf-tab，也不是放弃 tmux popup，而是按当前 tmux 客户端类型选择后端：

1
if [[ -n "${TMUX:-}" ]] && [[ "$(tmux display-message -p '#{client_control_mode}' 2>/dev/null)" == "1" ]]; then
2
  zstyle ':fzf-tab:*' fzf-command fzf
3
else
4
  zstyle ':fzf-tab:*' fzf-command ftb-tmux-popup
5
fi

这样做的效果是：

• 普通 shell 或普通 tmux：继续使用 ftb-tmux-popup，保留 popup 体验。
• iTerm2 tmux Control Mode：改用普通 fzf，避免在 Control Mode 里再创建 tmux popup。
• 大小写不敏感匹配：仍然由 matcher-list 负责，和展示后端互不冲突。

如果配置由 chezmoi 管理，就把这段逻辑写入 chezmoi 的 zsh 源文件，再定向同步到 ~/.zshrc。同步后建议重新打开 shell，或者执行：

1
source ~/.zshrc