VS Code highlight-words配置与实战指南

用VS Code写代码这些年，我越来越觉得编辑器里最容易被低估的功能不是代码补全，也不是调试器，而是“高亮”。以前排查线上日志的时候，满屏都是相似的时间戳和字段名，眼睛盯十分钟就开始发晕，后来把highlight-words这个关键词相关的配置梳理清楚之后，整个排查效率直接上了一个台阶。这篇博文我就围绕VS Code里如何设置highlight-words，把从安装、配置、调色到踩坑的完整过程写下来，希望对刚开始折腾VS Code布局和视觉反馈的读者有帮助。

1. 从“选中即高亮”到“主动标记”：先看清VS Code自带能力的天花板

1.1 内置高亮其实很聪明，但有个明显短板

VS Code默认就带一个“选中即高亮”的机制：你用鼠标双击某个变量名，或者用光标停留在某个标识符上，编辑器会自动把当前文件里所有相同文本的位置都标出来，右侧的缩略图（Minimap）里也会同步出现小色块。这个功能零配置、性能极好，在写Javascript、Python、Go这类强标识符语言时特别实用，等于免费送了你一个临时变量追踪器。

我用这个内置功能用了很长时间，但它有几个让我越来越难受的短板。

第一，高亮只作用于当前打开的文件。你在a.ts里选中了一个函数名，切到b.ts再看同名函数，那里是干干净净的，什么标记都没有。可实际干活的时候，一个业务逻辑往往横跨十几个文件，内置高亮根本做不到跨文件追踪。

第二，内置高亮的颜色是固定的一套，跟着当前主题走，没得调。浅色主题下是一种淡淡的灰蓝色，深色主题下又是另一种浅黄色，你想让它“醒目一点”或者“柔和一点”，对不起，改不了。

第三，这种高亮是“被动触发”的，也就是说光标一旦离开当前选中区域，高亮就消失了。你想让“TODO”“FIXME”这种词在整个项目里一直保持高亮，内置功能完全做不到。

1.2 为什么写代码时需要“主动标记”高亮

我用一个生活化的类比来解释主动标记的需求。

你拿一份纸质合同审阅，手边只有一支黄色荧光笔，看一句话就划一句话，划完翻页再看下一页，前面的标记还在，但你的注意力其实已经跟着光标走了。而highlight-words这类主动高亮工具给你的是好几支不同颜色的荧光笔，你可以在第一页用黄色标出所有“金额”，在第二页用粉色标出所有“违约责任”，标记不会因为你翻到下一页就消失，所有关键词在打开的文件里始终保持可见。

落实到具体工作场景，我举三个最常见的例子。

• 排查日志：日志文件里混着INFO、WARN、ERROR三种级别，把ERROR高亮成红色背景，一眼就能扫到问题行，不用再一行一行用眼睛过滤。
• 代码审阅：同事的PR里散落着好几个TODO和FIXME，把这些词永久高亮，打开文件就能看到哪些地方还没收尾。
• 联调接口：前后端联调时，把接口返回里的核心字段名（比如data、message、success）高亮出来，在冗长的JSON里定位字段就快很多。

说白了，内置高亮解决的是“光标在哪我关心哪”，主动高亮解决的是“我关心哪些词，它们出现在哪里”，后者更贴近真实工作中的注意力管理需求。

2. 三分钟装上highlight-words扩展，并跑通第一个配置

2.1 安装扩展的正确入口和版本选择

VS Code里装扩展基本是零门槛操作，但highlight-words这个名字在扩展市场里出现过多个相似扩展，所以第一步要先确认你装的是对的。

打开VS Code左侧的扩展图标（快捷键Ctrl+Shift+X），在搜索框输入highlight-words，回车后会出现一系列结果。我的建议是优先看评分高、下载量大、更新时间在最近一年内的那个。另外一个稳妥的办法是在扩展详情页看它的Extension ID，再和GitHub仓库或者VS Code Marketplace网页上的信息对一下，避免装成同名但功能完全不同的扩展。

安装完成后，如果之前的VS Code窗口已经开了很长时间，建议点一下命令面板（Ctrl+Shift+P）里的“Developer: Reload Window”重载窗口，确保扩展真正加载起来。这一步经常被新手忽略，装完插件不生效十有八九是没重载窗口。

2.2 第一份可直接复制的settings.json配置

安装完成后，打开设置页面：快捷键Ctrl+,进入用户设置，点击右上角的“打开设置(JSON)”图标，会看到一个settings.json文件。把下面这份配置直接粘进去，保存后窗口里所有打开的文件中，TODO、FIXME、BUG这三个词就会自动被高亮。

{ "highlightWords.words": ["TODO", "FIXME", "BUG"], "highlightWords.color": "#FFD54F", "highlightWords.textColor": "#1F1F1F", "highlightWords.borderRadius": "2px", "highlightWords.caseSensitive": false, "highlightWords.wholeWord": true, "highlightWords.showInStatusBar": true }

逐个解释这些配置项的作用。

• highlightWords.words：数组类型，存放你想要高亮的所有词。可以写业务关键词，也可以写代码注释里约定俗成的标记词。
• highlightWords.color：高亮背景色。这里用的是暖黄色#FFD54F，在大多数深色主题下都算醒目，但又不刺眼。
• highlightWords.textColor：高亮区域里的文字颜色。深色文字配浅黄背景，阅读体验比较舒服。
• highlightWords.borderRadius：高亮背景的圆角值。设为2px可以让高亮色块柔和一些，不会有那种锋利矩形的生硬感。
• highlightWords.caseSensitive：是否大小写敏感。false表示todo和TODO都会被识别，适合大多数注释标记的场景。
• highlightWords.wholeWord：是否全词匹配。true意味着TODO不会匹配到TODOLIST这种包含关系，能避免大量误报。
• highlightWords.showInStatusBar：是否在状态栏显示高亮词出现的次数，调试时很方便。

注意，不同版本的高亮扩展对配置项的命名可能略有差异，但大体的键名结构是稳定的。如果粘进去后发现某个配置项没有生效，先用最小化配置排查，不要急着怀疑全部设置。

2.3 验证配置是否生效的两种方法

配置保存后，怎么知道它真的生效了？

方法一：新建一个临时文件，敲一行包含TODO的注释，比如// TODO: fix this bug，然后看这个单词是不是立刻被色块包住。如果是，说明静态配置生效了。

方法二：用命令面板动态验证。按Ctrl+Shift+P，输入Highlight Words，你会看到这个扩展暴露出来的一系列命令，比如“Add Word To Highlight”“Remove Word From Highlight”“Clear All Highlights”等。选择“Add Word To Highlight”，输入一个你想高亮的关键词，比如ERROR，确定后当前文件里所有ERROR文本应该立即被高亮。用命令面板添加的好处是你不用频繁改配置文件，适合临时标记一个正在排查的变量名。

3. 手把手拆解核心配置项：颜色、匹配范围与状态栏信息

3.1 颜色与文字修饰：调整到不刺眼

高亮功能本身是好用的，但颜色配不好也会让人抓狂。我见过有人直接把高亮背景设成纯红色#FF0000，结果打开文件后像得了红眼病，看两分钟就受不了。所以颜色配置值得单独说一说。

在settings.json里，核心的颜色配置项有两个：highlightWords.color控制背景色，highlightWords.textColor控制文字颜色。再加上borderRadius控制圆角，就能拼出三种高性价比的视觉方案。

还有一个小技巧：用带透明度的颜色可以让高亮在任意主题下都不会和代码本身的语法高亮“打架”。比如把背景色写成rgba(255, 213, 79, 0.4)，半透明的效果既保留了提示性，又不会完全遮住原本的语法颜色。我自己实测下来，透明度控制在0.3到0.5之间最舒服。

如果你有多个重点词，尽量控制在一到两个颜色。颜色超过三种，视觉上会立刻变得杂乱，反而失去了高亮的提示意义。

3.2 大小写、全词匹配、搜索排除与性能上限

这几个配置项直接决定了“高亮会不会误报”和“会不会卡顿”。

先说大小写敏感。highlightWords.caseSensitive设为false的时候，你高亮todo，那么TODO、Todo、todo全都会被命中。好处是省心，坏处是有些字段名本身依赖大小写区分，比如前后端字段经常有Id和ID同时存在的情况，这时候就需要把caseSensitive设为true，只高亮你关心的那一种写法。

再说全词匹配。highlightWords.wholeWord我几乎永远设为true。举个例子，如果你高亮的是chat，而wholeWord是false，那么chatter这种词也会被你高亮出来，视觉噪音非常大。全词匹配能有效避免这种“包含关系”带来的误报。

关于性能上限，我这里有一个非常实用的配置项：highlightWords.maxHighlightsPerFile。它限制单个文件里最多高亮多少个匹配项。当你打开一个几千行的日志文件时，如果ERROR出现了上千次，逐一字面量渲染会让编辑器产生明显卡顿。我记得有一次直接打开了一个40MB的日志文件，高亮词一开，光标移动都掉帧，后来把上限设在500，编辑器立刻流畅起来。如果你不常打开超大文件，这个配置项可以不设置；一旦有卡顿，优先检查它。

3.3 状态栏与命令面板里的隐藏用法

配置好之后，状态栏会显示当前文件中高亮词出现的次数，这是showInStatusBar设为true的效果。比如你高亮了ERROR，状态栏会出现类似ERROR: 28的提示，告诉你这个文件里有28处错误标记。它会随着你切换文件和编辑内容实时更新。

命令面板里的“Add Word To Highlight”和“Remove Word From Highlight”我建议记熟。它们的意义在于可以把临时排查用的关键词和配置文件里的长期关键词分开：配置文件里只放TODO、FIXME这类常态化标记，临时要盯某个变量名时用命令面板添加，排查完再移除，不用每次打开settings.json改来改去。

如果你觉得每次打开命令面板输入命令还是麻烦，可以给这两个操作绑定快捷键。在键盘快捷键设置页面搜索Highlight Words，找到“Add Word to Highlight”和“Clear All Highlights”，分别绑定自己习惯的按键。我个人的习惯是把添加高亮绑定到Ctrl+Shift+H，把清除高亮绑定到Ctrl+Shift+G，排查问题的时候手基本不用离开键盘。

4. 更新版本的高级玩法：多组标记、动态高亮与跨文件搜索

4.1 多组标记：给不同关键词分配不同颜色

新版本的highlight-words扩展支持配置多组标记（Marks），每一组可以拥有独立的词列表和独立颜色。这个功能特别适合需要同时追踪多个语义的场景。

举个例子，我在代码审阅时的配置是这样的：

{ "highlightWords.marks": [ { "words": ["TODO", "FIXME"], "backgroundColor": "#FFB74D", "textColor": "#212121" }, { "words": ["BUG"], "backgroundColor": "#E53935", "textColor": "#FFFFFF" } ] }

这样配置之后，TODO和FIXME是橙黄色底，表示“待办事项”；BUG是红色底，表示“明确的问题”。打开一个文件，哪些地方是遗留任务、哪些地方是明显缺陷，一眼就能分清，不需要逐个单词去阅读上下文。

多组标记的使用建议是克制。我见过有人一次性给七八组词分别配上不同颜色，结果整个页面像个调色盘，反而失去了重点。两个到三个颜色组已经是舒适区的上限，再多不如直接去用搜索结果面板。

4.2 延迟触发、静默模式与“只在高亮待处理时显示”

扩展新版本里还有一些偏细节的配置项，其中delay是最值得关注的一个。

highlightWords.delay控制高亮渲染的延迟毫秒数。它的作用场景是：当你正在快速敲代码，每敲一个字符编辑器都会重新计算一次高亮匹配，如果一个文件很大，这种频繁计算会带来明显的输入延迟。这时候可以把这个值设成300或500，意思是停止输入300毫秒后再执行高亮计算，本地体验几乎无感，但CPU压力会小很多。

还有一个highlightWords.silent静默模式，开启后扩展不会在状态栏输出多余信息，界面更干净。我一般只在做录屏或者演示的时候开它，平时还是保持状态栏可见，毕竟那个计数信息对排查问题很有用。

至于“只在高亮待处理时显示”这类选项，实际使用中更多是和搜索面板联动时才体现意义，平时保持默认就好，不必为了用而用。

4.3 和搜索面板联动的实际效果

highlight-words扩展不只是编辑器里的静态高亮，它和VS Code内置的搜索面板有不错的联动效果。

当你用Ctrl+Shift+F打开全局搜索，搜索某个关键词时，所有匹配项在搜索结果列表里会带出文件名和上下文高亮。同时，如果你在工作区打开了多个文件，且这些文件里包含你通过扩展高亮的词，那么切到任何一个文件时，相应的扩展高亮也会立即显示。两套高亮机制叠在一起，一个负责“搜”，一个负责“盯”，配合起来非常顺手。

我的使用模板是这样：拿到一份线上日志目录后，先用命令面板把ERROR和Exception加入高亮，然后在搜索面板里搜这两个词，确认出现频率最高的文件是哪些。接着逐个打开这些文件，因为扩展高亮已经生效，重点行会直接跳进眼睛里，省去了在搜索结果和文件之间反复横跳的步骤。

5. 几款主流高亮扩展怎么选：实测对比后我的推荐

5.1 同类扩展能力对比

我现在VS Code里实际装过的相关扩展有三类：内置选中高亮、highlight-words，以及另一种功能更重的Highlight扩展（由fabiospampinato开发）。三者的能力边界完全不同。

从表格可以看出来，内置高亮解决的是“零成本临时查看”，highlight-words解决的是“轻量多词标记”，而Highlight扩展则面向“重度定制玩家”，适合愿意花时间研究每一个视觉细节的人。

5.2 不同场景下的选型思路

如果你的诉求只是“写代码时看同一个变量名方便一点”，内置高亮完全够用，不用装任何扩展。

如果你需要在日常工作中持续追踪TODO、FIXME这类语义标记，或者在日志排障时频繁对特定错误码打标，我的建议是直接上highlight-words。它的配置量很小，核心配置项不超过十个，半小时内就能调出自己习惯的视觉方案。

如果你是前端设计师或者对编辑器视觉有特殊偏好，需要给不同语法结构设计完全不同的高亮规则，那么Highlight扩展会更适合你。它有更细粒度的控制选项，能针对注释、字符串、关键字分别设置高亮样式，但相应地学习成本也更高。

就我自己而言，现在的主力配置就是highlight-words，配合两到三组mark标记，已经覆盖了绝大多数工作场景。重型的Highlight扩展我装了之后反而用得很少，因为它功能太多，配置一多就会产生“配置焦虑”，不划算。

6. 调色不生效、颜色太扎眼、标记消失：我踩过的高亮配置坑

6.1 颜色不生效的排查链路

踩坑最多的场景就是配置写了但高亮颜色不变化。

我在帮同事调配置时见过几种典型情况，整理成排查顺序：

1. 确认扩展确实在启用状态。扩展面板里搜索highlight-words，如果显示Disable说明已启用；如果显示Enable说明被禁用了，点Enable恢复。
2. 确认settings.json里的键名拼写无误。这是最常见的坑，比如有人把highlightWords.color少写了一个s，写成了highlightWord.color，配置自然不生效。大小写一个字母都不能差。
3. 确认当前是用户设置生效。VS Code有用户设置和工作区设置两层，如果.vscode/settings.json里有一份工作区配置覆盖了用户配置，那么你在用户配置里的改动可能被压住。检查左下角有没有显示工作区设置的提示。
4. 确认没有其他扩展或主题覆盖颜色。有些语义高亮扩展和特定主题会强制覆盖扩展设置的颜色，这种冲突只能通过关闭相关扩展来定位。
5. 重载窗口。Ctrl+Shift+P执行“Developer: Reload Window”，有时候配置写入后需要重新加载才生效。

按照这个顺序排查，绝大多数“配置了没反应”的问题都能定位到原因。

6.2 扩展高亮与内置高亮叠加时的阅读体验调整

当你既开着内置选中高亮，又开着highlight-words扩展高亮时，同一个文件里可能出现两套颜色同时闪烁的情况。内置高亮的颜色通常是主题自带的浅蓝色或浅灰色，扩展开启的自定义颜色往往更鲜艳，两个叠在一起很容易让人分不清哪个是“当前选中位置”、哪个是“主动标记”。

我的应对方案是拉开两者在视觉上的差异。具体操作有两个方向。

• 把扩展高亮调得更醒目（比如用暖黄底、深色字），让它和系统那种淡淡的内置高亮在颜色上明显区分开。
• 如果你觉得两套高亮太乱，可以在设置里搜索editor.selectionHighlight，把它设成false，关掉内置的选中高亮，让扩展高亮独占视觉焦点。这个方法适合那些主要依赖highlight-words做标记、不依赖临时选中高亮的用户。

6.3 一个重要提醒：版本更新后的配置迁移

最后提醒一个很容易被忽略的问题：扩展升级可能导致配置项失效。

我自己经历过一次，某次升级后发现之前配置的高亮颜色全部失效了，查了半天才发现是新版引入了marks多组标记机制，旧的顶层配置方式被安排到了marks体系下面。当时我还在用旧版的配置键，新版本直接不认了。

所以升级扩展后，如果发现配置没生效，先去扩展详情页翻一下它的Changelog，看看配置项有没有改名。其次，保存一份旧配置的备份再动手改，避免改到一半回不去。

我的迁移习惯是：把原来用顶层配置书写的高亮词整理成marks数组的多组结构，每组各管一个语义，这样视觉功能更清晰，未来再新增关键词时直接在对应组里加词就行。

如果你现在只是用了一个很简单的配置，比如只高亮TODO一个词，提醒自己注意代码里还有未完成的工作，那么配置迁移的影响对你来说很小，保持简单其实是最省心的用法。