终端Raw模式与ANSI语法高亮实现指南

终端里做界面，最让人又爱又恨的东西就是 ANSI 转义序列。爱它，是因为只要一行\e[38;5;208m，你就能在任何支持颜色的终端里画出想要的层次；恨它，是因为大多数 UI 框架会把你的字符串当作纯文本处理，帮你转义、帮你计算宽度、帮你套上统一的样式，于是你精心拼进去的颜色码全部变成了原样显示的乱码。Sequin 这类终端界面组件库默认就是这个思路：它替你管格式，你只管给内容。但做日志查看器、diff 面板、REPL 输出回放这类需求时，你恰恰需要反过来——自己要控制每一个字节的输出。这时候就得启用 Raw 模式。这篇内容讲的就是这件事：Raw 模式打开之后，字符串怎么直通渲染层，ANSI 序列该怎么组织，语法高亮器怎么写，宽度和状态残留这两个坑怎么绕，以及一套可以直接抄的完整实现。适合已经能跑起基本终端面板、想进一步控制输出细节的人看；完全没碰过 ANSI 的也能跟，因为我会把最小必要知识先铺一遍。

1. 先把“高亮”这件事拆开看

1.1 Raw 模式到底改变了什么

先把概念对齐。终端面板里的“渲染”其实分两层：上层是组件，负责布局、分块、滚动；下层是终端模拟器，负责把字节流翻译成像素。中间的框架一般会插一脚，把你的文本做两件事——转义特殊字符，以及套上它自己的样式模板。默认模式下，你写"\e[32mgreen\e[0m"，框架看到的是一个普通字符串，它会把里面的 ESC 字符当成需要转义的普通内容，最后你看到的是一串[32mgreen[0m；或者它干脆把整段文本统一染成它认为合适的颜色，你的绿色被覆盖掉。这不是 bug，这是设计的默认行为，因为绝大多数场景下用户不需要关心这些。

Raw 模式做的事就一句话：关掉中间这一脚，让你的字符串原样抵达渲染层。开了之后，框架不再转义、不再包装样式，字符串里的 ESC 字节被当作控制指令直接送给终端。自由度和责任是同时到来的——颜色、缩进、清行、光标移动全部归你管，一旦序列写错或者忘了收尾，后果也全部由你承担。我用它主要覆盖四类场景：带颜色的日志尾部跟踪、代码片段或 diff 的高亮展示、把外部命令的彩色输出原样贴进面板、以及需要精细控制刷新（比如只重绘某几行）的动态视图。这四类的共同点是：颜色的语义来自内容本身，框架不可能猜得到，只能由调用方给。

1.2 ANSI 转义序列的最小知识集

不需要背整本 ECMA-48，掌握一个子集就够用了。所有序列都从 ESC（字节0x1B，Elixir 里写"\e"）开始，后面跟一个引导字符决定序列类型。我们要用的几乎全是 CSI，也就是ESC [，写作"\e["。CSI 之后的数字是参数，用分号分隔，最后一个字母是终止符。终止符m对应 SGR（Select Graphic Rendition），也就是“样式设置”，这是高亮的全部基础。

注意：终止符不能省。\e[32后面不带m，终端会一直等后续字节，直到遇到一个合法终止符为止，表现出来就是后面一大段输出全被吃掉或者错乱。

SGR 参数里最常用的部分我列成表，写主题配色时直接查：

有个容易混的点：38;5;n和38;2;r;g;b都归38管，你要么给 256 色模式传一个索引，要么给真彩模式传三个分量，别混着写。另外参数可以合并，\e[1;38;5;208m等于“加粗 + 橙色前景”一次设定。合并能减少字节数，在每秒推几十帧的场景里这点开销不算大，但代码会更清爽。

1.3 三条染色路线的取舍

真要做高亮，路口有三条，别一头扎进去就写，先看清楚各自的代价。

我做过一段时间的横向对比：如果只是给标题刷个颜色，第一条路足够，别折腾。如果是展示源码或日志，第二条路是主力，因为你要的不只是“这段是代码”，而是“这个关键字是紫色、这个字符串是绿色、这个注释是灰色”。第三条路只在一次性渲染、不需要动态刷新时才划算——起一个进程换一份高亮，成本可以接受；但如果面板每秒推一帧，那就是每秒起一个进程，很快就撑不住了。

2. Raw 模式的机制、边界与开启方式

2.1 字符串从 Elixir 到终端的完整链路

理解链路能省掉很多猜测。你的字符串在 Elixir 里是二进制，进入渲染环节后一般会被拼进 iodata（二进制与嵌套列表的混合结构，避免反复拼接拷贝），然后由一个下发通道送给前端渲染层，前端再塞进 DOM 的文本节点或者 canvas 里画出来。默认模式在“进入 iodata 之前”这一步会做转义和样式包装，Raw 模式跳过这一步，同时也会跳过配套的几件事：不自动换行、不自动补齐、不自动对齐。

这就解释了为什么很多人第一次开 Raw 会遇到同样的现象：内容能显示，但一旦有中文或者稍微长一点就整块错位，而且错位会传染到后面的所有元素。因为框架帮你算宽度的逻辑关了，它现在把整段字符串当“一个看不见宽度的整体”或者“按字节数算宽度”来处理，你塞进去的每个\e[38;5;208m（12 个字节）都被算进了可见宽度里。这是下一节的主题。

2.2 开启方式与最小可运行示例

以我手上这一版为例，开关放在构造输出块的地方，传raw: true就行。不同版本的函数名可能略有差异，核心就是找那个接收字符串、决定“怎么渲染这段文字”的入口，把 raw 打开。

# 默认模式：框架接管格式 Sequin.new() |> Sequin.text("\e[32mOK\e[0m 编译通过") # Raw 模式：字符串原样下发 Sequin.new(raw: true) |> Sequin.text("\e[32mOK\e[0m 编译通过")

第一段把 ESC 当成普通字符，你看到的是字面上的[32mOK[0m，绿不绿取决于框架心情；第二段把 ESC 原样送出去，你看到的是绿色的OK，后面接一段默认色的中文。验证是否真的生效有个小技巧：先只发"\e[41m \e[0m"（一个红色背景的空格）。Raw 生效的话你会看到一小块红色方块；没生效的话你会看到一串字符。这个测试比看颜色更可靠，因为它不依赖终端的前景色配置。

如果你的版本没有raw:这个键，等价做法是找“预格式化文本”或者“直接输出”类的接口，思路一样：绕开自动包装。别去改框架源码，先看看文档里有没有这个逃生口。

2.3 宽度与截断：Raw 模式的第一号陷阱

这是最容易翻车的地方，值得单独说。终端里一个字符占几列，和它的字节数没关系，和它的码点也不完全对等。ASCII 是 1 列，中日韩文字和大部分全角符号是 2 列，Emoji 通常是 2 列，零宽连接符是 0 列。你自己拼的转义序列是 0 列，但它的字节数可能很长。所以“长度”这个词在这里有三个含义：字节数、码点数、可见列宽。布局只认第三个。

标准做法是：计算宽度前先把转义序列剥掉，再按字符的实际显示宽度累加。剥离用一条正则就够，覆盖绝大多数 SGR 和 CSI 序列：

@strip_ansi ~r/\e\[[0-9;]*[A-Za-z]/ def visible_width(text) do text |> String.replace(@strip_ansi, "") |> String.to_charlist() |> Enum.reduce(0, fn cp, acc -> acc + char_cols(cp) end) end # 只覆盖常见的宽字符区间，够用且不引入额外依赖 defp char_cols(cp) when cp in 0x1100..0x115F or cp in 0x2E80..0xA4CF when cp in 0xAC00..0xD7A3 or cp in 0xF900..0xFAFF when cp in 0xFE30..0xFE6F or cp in 0xFF00..0xFF60 when cp in 0xFFE0..0xFFE6 or cp in 0x1F300..0x1F64F, do: 2 defp char_cols(_), do: 1

截断的难点在于不能把序列切断。你按列数硬切字节，很可能切在\e[38;5;2中间，剩下的08m就变成了普通文本，直接污染画面。正确姿势是按“转义段”和“文本段”分开处理：转义段无条件保留，文本段按剩余列数取前缀，最后补一个\e[0m收尾。这个函数后面我会给出完整版。

2.4 SGR 是状态机，不是标签对

写 HTML 的人习惯<span>...</span>成对出现，天然闭合。ANSI 不是这样，它是一台有状态的小机器：你发一个\e[32m，终端就把“前景绿”这个状态记下来，直到遇到下一个改变前景的参数或者0重置。这意味着两个后果。

第一，忘写重置会污染后续所有输出。面板里一个块漏了\e[0m，下一个块的边框、标题、甚至整个页面的底色都会变成绿色。排查这类问题很痛苦，因为症状出现在下游，根因在上游。我的习惯是写一个paint/2函数，任何上色都必须经过它，函数内部强制在结尾补\e[0m，从源头上消灭手工拼序列的机会。

第二，嵌套时不能简单叠加。比如你给整行设了背景色，中间某一段要高亮前景，那一段结束后必须把前景恢复到“整行的颜色”而不是默认色，否则后半行就掉回了默认前景。稳妥的写法是每个 token 自成闭环：开序列 + 文本 + \e[0m，让每个染色片段互不干扰。代价是字节数变多，收益是永远不用想“我现在处于什么状态”。

3. 手写一个能用的 ANSI 高亮器

3.1 词法切分：规则顺序就是优先级

做语法高亮，最朴素的思路是“按顺序套正则替换”。这个思路必翻车，因为替换是全局的、无序的：你先给def上色，再去处理字符串，字符串里的def也被上了一层，最后颜色互相打架。正确做法是从左到右单向扫描，每次只在当前位置匹配，命中就消费掉这段，绝不回头。这一遍扫下来天然解决了嵌套和重叠问题。

规则的顺序就是优先级，越靠前越优先。经验排序是：注释 > 字符串 > 数字 > 关键字 > 标识符。注释排最前，因为# 这里有个 "引号这类内容太常见，注释内的引号不该被当成字符串起始。字符串排第二，因为字符串里可能出现任何关键字。代码长这样：

@rules [ {:comment, ~r/#[^\n]*/}, {:string, ~r/"(?:[^"\\]|\\.)*"/}, {:number, ~r/\b\d+(?:\.\d+)?\b/}, {:keyword, ~r/\b(def|defp|defmodule|do|end|fn|case|when|if|else|true|false|nil)\b/}, {:call, ~r/\b[a-z_][a-zA-Z0-9_]*[?!]?(?=\()/} ] defp match_at_head(input) do Enum.find_value(@rules, :none, fn {kind, re} -> case Regex.run(re, input, return: :index) do [{0, len} | _] -> <<token::binary-size(len), rest::binary>> = input {:ok, kind, token, rest} _ -> nil end end) end

return: :index让正则返回字节偏移而不是匹配到的字符串，这样{0, len}就明确表示“在开头命中了 len 个字节”。这个细节很关键，用字符串匹配再回头算位置会踩到多字节字符的坑。

3.2 把颜色和语法解耦：主题表怎么设计

高亮器不该硬编码颜色。语法类别（comment、string、keyword）和具体颜色之间要隔一层主题表，这样换配色只改一张表，不动逻辑。主题表的值直接存 SGR 参数列表，运行时拼成序列：

@themes %{ dark: %{ comment: [90], string: [38, 5, 114], number: [38, 5, 179], keyword: [1, 38, 5, 176], call: [38, 5, 81], plain: [39] }, light: %{ comment: [38, 5, 245], string: [38, 5, 28], number: [38, 5, 130], keyword: [1, 38, 5, 90], call: [38, 5, 25], plain: [39] } }

这里有个实际取舍：真彩（38;2;r;g;b）颜色更准，但序列长、对老终端不友好；256 色（38;5;n）兼容性好，色板有限但足够区分语法类别。我的选择是主题表里统一用 256 色，因为面板经常要在不同机器、不同终端主题下看，真彩的对比度很难保证——同一个橙，在暗底上很好看，换到亮底就糊了。所以准备两套主题、按背景切换，比死磕一套真彩更实用。

3.3 包裹而非拼接：paint 与注入防护

前面说过，每个 token 自成闭环。这个函数虽小，但它是整个体系的安全阀：

defp paint(token, kind, theme_key) do codes = @themes |> Map.fetch!(theme_key) |> Map.get(kind, [39]) "\e[" <> Enum.join(codes, ";") <> "m" <> escape_user(token) <> "\e[0m" end # 用户内容里如果自带 ESC，一律剥掉，防止破坏外层状态 defp escape_user(text), do: String.replace(text, "\e", "")

escape_user那行别省。高亮器处理的内容经常来自外部——日志文件、数据库里的报错信息、别人贴进来的片段，里面完全可能藏着 ESC 字节。如果不剥，一段精心构造的文本就能把你的面板改成任意样子，或者把后面的所有元素染色。剥掉 ESC 会损失一点“原样显示”的保真度，但换来的是可预测性，我认为非常值。

3.4 完整的扫描器与跑通验证

把上面几块拼起来，就是一个不依赖任何第三方库、两百行以内搞定的高亮器：

defmodule Fmt.Highlight do @rules [ {:comment, ~r/#[^\n]*/}, {:string, ~r/"(?:[^"\\]|\\.)*"/}, {:number, ~r/\b\d+(?:\.\d+)?\b/}, {:keyword, ~r/\b(def|defp|defmodule|do|end|fn|case|when|if|else|true|false|nil)\b/}, {:call, ~r/\b[a-z_][a-zA-Z0-9_]*[?!]?(?=\()/} ] @themes %{ dark: %{comment: [90], string: [38, 5, 114], number: [38, 5, 179], keyword: [1, 38, 5, 176], call: [38, 5, 81], plain: [39]}, light: %{comment: [38, 5, 245], string: [38, 5, 28], number: [38, 5, 130], keyword: [1, 38, 5, 90], call: [38, 5, 25], plain: [39]} } def render(text, theme \\ :dark) do scan(text, [], theme) |> Enum.reverse() |> IO.iodata_to_binary() end defp scan("", acc, _theme), do: acc defp scan(input, acc, theme) do case match_at_head(input) do {:ok, kind, token, rest} -> scan(rest, [paint(token, kind, theme) | acc], theme) :none -> <<cp::utf8, rest::binary>> = input scan(rest, [<<cp::utf8>> | acc], theme) end end defp match_at_head(input) do Enum.find_value(@rules, :none, fn {kind, re} -> case Regex.run(re, input, return: :index) do [{0, len} | _] -> <<token::binary-size(len), rest::binary>> = input {:ok, kind, token, rest} _ -> nil end end) end defp paint(token, kind, theme) do codes = Map.get(Map.fetch!(@themes, theme), kind, [39]) "\e[" <> Enum.join(codes, ";") <> "m" <> String.replace(token, "\e", "") <> "\e[0m" end end

调用就一行，输出直接塞给 Raw 模式的文本块：

code = "def hello(name), do: \"hi #{name}\" # 打招呼" IO.puts(Fmt.Highlight.render(code, :dark))

跑起来应该看到def是加粗紫、hello是青蓝、字符串是绿、注释是灰。如果全是默认色，先确认是不是忘了开raw: true——这是我见过次数最多的“高亮器没生效”原因，占了大概七成。

3.5 性能边界：什么时候必须加缓存

朴素扫描是逐字符推进的，遇到:none就消费一个码点继续。对一个几百行的文件做一次全量高亮，在我这边大概是一两毫秒量级，完全可以接受；但如果你打算每帧重绘整屏、每秒三十帧，那就是每秒几十毫秒花在重复计算同样的内容上，白白浪费。两个优化按性价比排序。

第一个是只高亮变化的部分。日志场景里历史行不会变，新行才需要处理。做法是维护一个已经渲染好的行列表，新内容到了只处理增量，把结果追加进去，整个帧再拼一次。这能省掉 90% 以上的重复计算，改动量也不大。

第二个是缓存到行级别。用一个 map 存“行内容 → 渲染结果”，命中就跳过扫描。这招在处理滚动回看、反复切窗口时特别有效，但要注意给 map 设一个容量上限，否则长时间运行的进程会慢慢把内存吃光。我一般是超过两千条就清掉最早的。

注意：别去预编译正则之后再指望它解决一切。Regex在 Elixir 里编译后复用确实比每次编译快，但真正的大头是“扫描次数”，不是“单次匹配速度”。优化方向搞错，改半天看不到效果。

4. 实操：搭一个会动的日志高亮面板

4.1 环境与依赖准备

环境这块要求不高。Elixir 1.15 以上、OTP 26 以上基本都能跑，主要图的是String.to_charlist/1和相关 Unicode 处理的稳定性。如果是笔记本环境里跑（比如 Livebook），直接装依赖、开一页新的就行；如果是独立应用，把Sequin加进mix.exs的依赖列表，mix deps.get拉一下。

# mix.exs 片段 defp deps do [ {:sequin, "~> 0.1"} ] end

版本号按你实际能拉到的最新稳定版填，别照抄。装完之后先跑一个最小验证：开 raw、发一个红底空格，确认能看到色块。这一步花两分钟，能帮你排掉后面一半的诡异问题——很多“颜色不对”最后都定位到“raw 压根没生效”。

4.2 数据管道：读取、切窗口、高亮、推帧

整个面板的数据流是单向的，串起来就是四条：

1. 读取：从文件尾部按块读，或者订阅一个日志输出流，拿到新的一批行。
2. 切窗口：只保留最后 N 行（N 取决于面板高度），早的丢弃。窗口滑动是视觉效果的关键。
3. 高亮：对窗口内每一行跑Fmt.Highlight.render/2，拼成一块带换行符的文本。
4. 推帧：开 raw 的文本块，把整块内容塞进去，触发重绘。

defmodule Panel do alias Fmt.Highlight @max_lines 40 def frame(lines, theme) do body = lines |> Enum.take(-@max_lines) |> Enum.map_join("\n", &Highlight.render(&1, theme)) "\e[2J\e[H" <> body end end

开头那个\e[2J\e[H是清屏加归位，作用相当于“擦干净再画”。这两个序列是判断你 Raw 模式是否真的掌控输出的最好证据：如果清屏没生效，内容是一层层滚上去的，说明序列没被识别；如果清屏生效但内容闪烁严重，那是帧率或者重绘量的问题，后面讲。

4.3 参数实测：刷新间隔、行数与色深

参数没有标准答案，但有钱包——每一次不必要的重绘都要花 CPU 和带宽。这几个数是我在几种场景下反复调整后比较稳的组合：

刷新间隔我试过 100ms，效果是画面流得很顺，但 CPU 占用一直挂在 20% 下不来，风扇开始叫。改到 500ms 之后占用降到个位数，肉眼几乎看不出延迟差异。原因很简单：人眼对“每半秒来一批新行”的接受度远高于“每 100 毫秒重画一次整屏”的代价。窗口行数也别贪多，40 行以上就要小心——全量重绘的开销是线性增长的，而屏幕根本显示不下那么多。

4.4 我在这个环节踩的四个坑

坑一：清屏序列和滚动混用。一开始我用\e[2J清屏再加内容，发现日志短的时候没问题，日志一长画面就开始跳。后来才明白问题出在“清屏之后光标位置”和“框架自己也在调整滚动位置”这两件事打架。改成只更新可见区域、不清屏，跳动就没了。经验：如果框架本身提供了容器滚动，就别再自己发清屏指令，二选一。

坑二：真彩在浅色终端上惨不忍睹。调试时在暗色主题下配的色，换到浅色终端一看，注释灰和背景糊成一片。这个没法靠调一个参数解决，只能准备两套主题，并且提供一个手动切换入口。

坑三：截断切在序列中间。前文提过，我是真踩了一遍。表现很迷惑：大部分行正常，偶尔某一行后面拖出一串m或者[0。定位办法是把渲染输出里的 ESC 替换成可见的<ESC>打印出来，一眼就能看到断在哪。修法就是按段处理，别按字节切。

坑四：多行内容里的反引号和内联样式。如果你的日志本身带 markdown 风格标记，高亮器会把它当普通文本染色，视觉上很乱。这类内容建议在进高亮器之前先做一遍清洗，或者干脆给这类行套一个“纯文本”类别，只上基础前景色。

5. 常见问题与排查速查

5.1 样式串味、颜色残留的排查顺序

症状是“某个块之后所有内容都变色了”。别急着改渲染逻辑，按这个顺序查，通常三步内能定位：

1. 先看有没有漏\e[0m。搜索你的代码里所有手写的\e[，确认每一处都有对应的重置；如果用统一的paint/2包装，那大概率不是这里。
2. 再看有没有序列被切断。异常截断会导致后半截变成普通文本，或者残留一个悬空的状态设置。用<ESC>可见化打印出来对照。
3. 最后看嵌套恢复。整行设了背景色、内层 token 结束后回了默认色，后半行就会掉回默认前景。这种情况不是“漏重置”，而是“重置过头”，症状是半行正常半行不对，很好区分。

5.2 对齐错位与越界的定位方法

症状是右边框对不齐、长行把布局顶出去、或者换行位置莫名其妙。核心原因永远只有一个：你在用字节数或者码点数冒充列宽。验证办法很土但有效：造一行“纯 ASCII 20 字符”和一行“10 个中文字符”，两者可见宽度都应该是 20，如果渲染出来宽度不一样，说明宽度计算没考虑双宽字符。修好了这个，再去检查截断是否保留了完整的转义段。

5.3 复制粘贴带出一堆控制符

这个坑挺尴尬的：面板里看着很漂亮，用户一选中复制，粘到别处就是一堆[38;5;81m。这不是你的错，是终端的选中行为把 ESC 字节也复制走了。解法是提供一份“无格式副本”：渲染时保留一份原始纯文本，或者用剥掉序列的正则现算，放在一个可复制的区域里。我一般是把这份副本放在面板下方，标题写清楚“纯文本”，省得用户来回折腾。

5.4 一页速查表

最后说一个我用了很久的习惯。任何新写的 ANSI 片段，先单独丢进一个最小的 Raw 块里看效果，别一头扎进复杂布局里调。因为高亮器的错误和布局的错误长得很像——都是“位置不对”“颜色不对”，混在一起排查会让人怀疑人生。把上色和布局分开验证，两个都单独确认没毛病，再合起来，这个习惯帮我省下的时间比任何优化技巧都多。另外，主题表里我会特意留一个plain: [39]的条目，给那些“不想被染色但必须走同一条渲染路径”的内容用，这样所有输出都经过同一个入口，不会出现某条支路绕过收尾逻辑导致状态泄漏。这个小心思看着不起眼，但在长跑的面板里，它是保持画面干净的关键。