June 21, 2026 · 9:12 AM

Claude Code SDK #26：Fullscreen rendering 全解——alternate screen × 虚拟滚动 × 鼠标事件，让长会话不再闪屏

Fullscreen rendering 不是把终端窗口最大化，而是让 Claude Code 使用 alternate screen buffer、只渲染可见消息，并接管滚动、搜索、复制等交互。本篇拆解开启方式、配置变量、tmux / iTerm2 边界和一套可直接照做的调参顺序。

Claude Code SDK 每日技术拆解 @wei

开长会话时，Claude Code 最烦人的不是模型慢，而是终端跟不上：输出一多，屏幕闪、滚动条跳、输入框被顶来顶去。fullscreen rendering 解决的就是这个底层手感问题。它不是把窗口最大化，而是让 Claude Code 像 vim / htop 一样接管终端的 alternate screen，只渲染当前可见的消息。官方文档把它标成 opt-in research preview，并要求 Claude Code v2.1.89 或更高版本。1

一句话先放前面：如果你经常在 VS Code integrated terminal、tmux、iTerm2 里跑长任务，或者一边等 Claude 改代码一边回看前文，/tui fullscreen 很可能是比换主题、改快捷键更明显的体验升级。

1. Fullscreen 不是全屏窗口，而是换了一条渲染管线

名字容易误导。这里的 fullscreen 和 macOS 绿色按钮、Windows 最大化没关系。它描述的是 Claude Code 使用终端为全屏程序预留的绘制区域，也就是 alternate screen buffer。官方文档明确说，这个模式可以在任何窗口大小下工作。1

经典渲染更像「不断往终端 scrollback 里追加文本」。会话越长，终端要处理的历史输出越多；流式工具结果刷出来时，某些终端就会开始闪、跳、卡。

fullscreen rendering 换了策略：对话活在 alternate screen 里，输入框固定在底部，只把当前可见消息留在 render tree 中。官方文档把收益说得很直接：长对话里内存使用保持平坦，更新时发给终端的数据更少。1

Classic renderer 与 fullscreen renderer 的渲染差异 — 自制示意图：classic renderer 继续写入原生 scrollback，fullscreen renderer 把当前可见消息放进 alternate screen；依据官方 fullscreen 文档整理。1

这个设计的代价也很清楚：你的 Cmd+f、tmux search、终端原生拖选，不再直接面对完整会话文本。因为文本不在原生 scrollback 里，Claude Code 需要自己提供搜索、滚动、选择和复制。1

2. 什么时候该开：看症状，不看信仰

这不是「所有人必须开」的配置。官方在 terminal configuration 页把它放在一个很具体的症状下面：如果 display flickers 或 scrollback jumps，切到 fullscreen rendering。2

我会按这张表判断：

症状	是否建议开	原因
Claude 正在跑工具，屏幕频繁闪一下	是	fullscreen rendering 会减少每次更新发送给终端的数据量。1
长会话里滚动位置突然跳到顶部或底部	是	官方把「scroll position jumps」列为该模式要处理的场景。1
你主要用 VS Code integrated terminal、tmux、iTerm2	倾向开启	官方说差异在渲染吞吐成为瓶颈的终端里最明显，并点名这些环境。1
你高度依赖终端原生选中复制、tmux copy mode	先谨慎	fullscreen 会捕获鼠标事件；需要用内置选择，或临时按住终端指定修饰键走原生选择。1
你在 iTerm2 的 `tmux -CC` integration mode 里工作	不建议	官方写明 fullscreen 与 iTerm2 tmux integration mode 不兼容。1

注意边界：tmux 里的普通会话可以用，但鼠标滚轮需要 tmux mouse mode。官方给的配置是 set -g mouse on，否则滚轮事件会被 tmux 接走。1

3. 开启方式：先 `/tui fullscreen`，别急着改 shell profile

最稳的入口是当前会话里运行：

/tui fullscreen

这个命令会保存 tui 设置，并带着当前对话重启到 fullscreen renderer；你不用担心正在进行的上下文丢掉。想确认当前渲染器，运行 /tui 不带参数即可。1

如果你要从 shell 临时启动，也可以用环境变量：

CLAUDE_CODE_NO_FLICKER=1 claude

官方文档说 tui 设置和 CLAUDE_CODE_NO_FLICKER 等价；/tui 命令 relaunch 时会清掉进程里的 CLAUDE_CODE_NO_FLICKER，让它写入的设置生效。1

Fullscreen rendering 的配置路径 — 自制配置卡：优先用 `/tui fullscreen` 试当前会话，再按滚轮、鼠标、回退需求追加环境变量；依据 fullscreen 与环境变量文档整理。3

几个配置别混用：

想把它设成默认：用 /tui fullscreen 或在 settings 里把 tui 设为 fullscreen。settings 文档把 tui 描述为 terminal UI renderer，并说明 fullscreen 对应无闪烁的 alt-screen renderer。4
想调滚轮速度：设 CLAUDE_CODE_SCROLL_SPEED=3。官方说它接受 1 到 20，也接受 0.5 这类小数；3 接近 vim 的默认滚动速度。1
想关掉滚轮加速：在 settings 里把 wheelScrollAccelerationEnabled 设为 false。这个设置需要 Claude Code v2.1.174 或更高版本。4
想回到经典渲染：运行 /tui default，或设置 CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1。官方说明这个变量会强制 classic renderer，并让对话继续留在终端原生 scrollback。3

4. 鼠标、搜索、复制：开 fullscreen 后最该重新训练的三件事

第一件是滚动。fullscreen 内部处理滚动，常用键是 PgUp / PgDn 半屏滚动，Ctrl+Home 跳到开头，Ctrl+End 跳到底部并恢复 auto-follow。MacBook 没有这些键时，用 Fn+↑/↓/←/→ 发出对应按键。1

第二件是搜索。原来的 Cmd+f 看不到 alternate screen 里的完整对话。要搜索，会先按 Ctrl+o 进入 transcript mode，再用 / 搜索，用 n / N 跳到下一个或上一个匹配。需要把全文交还给终端原生 scrollback 时，在 transcript mode 里按 [。1

第三件是复制。fullscreen 会捕获鼠标事件：点击输入框可移动光标，点击折叠的工具结果可展开，拖选文本会在 mouse release 时自动复制。要临时使用终端原生选择，按住对应修饰键再拖选，例如 iTerm2 用 Option，多数其他终端用 Shift。1

Fullscreen 模式下的回看、搜索与复制快捷键 — 自制速查图：fullscreen 下的回看、搜索、复制操作入口；依据官方 fullscreen 文档整理。1

如果你就是不想让 Claude Code 管鼠标，可以这样启动：

CLAUDE_CODE_NO_FLICKER=1 CLAUDE_CODE_DISABLE_MOUSE=1 claude

官方说明这个变量会禁用 mouse tracking，但键盘滚动仍可用；代价是失去 click-to-position-cursor、click-to-expand、URL click 和鼠标滚轮在 Claude Code 内部滚动。1

5. 推荐配置顺序：三步就够

如果你今天只想把手感调顺，不需要一次读完所有环境变量。我建议这样做：

在当前长会话里运行 /tui fullscreen，观察输入框是否固定在底部。官方也把「输入框不再随着输出移动」作为 fullscreen active 的可见信号。1
用一段会产生连续输出的任务测试滚动、搜索、复制：PgUp 回看，Ctrl+o 进 transcript mode，/ 搜关键词，拖选一段文本。
如果滚轮不顺，再按场景补变量：慢就调 CLAUDE_CODE_SCROLL_SPEED，想保留原生选中就加 CLAUDE_CODE_DISABLE_MOUSE=1，要彻底回 classic 就用 /tui default 或 CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1。3

最后给一个判断标准：如果你的 Claude Code 主要跑短问答，classic renderer 完全够用；如果你把它当长时间驻留的代码工作台，fullscreen rendering 值得默认开启。它修的不是模型能力，而是终端这层「人机接触面」。这层一旦顺了，长任务才真的像在一个稳定的工作台里发生。