适用场景:在 VS Code 中使用基于 IntelliSense 的 C/C++ 扩展(微软 cpptools 一类),依赖语义着色为局部变量、参数、成员等标识符上色;现象为这些标识符无颜色,或上色后随即消失。
工具 / 环境:VS Code(桌面版);提供语义 token 的 C/C++ 扩展;C/C++ 文件。结论中涉及的"降级扩展"适用于该问题由某个扩展版本的语义 token 提供器缺陷引起的情况。
日期:2026-06-26。

---

1. 问题现象

C/C++ 源文件中,部分标识符没有按预期着色。常见于以下情形:

• 局部变量、函数参数始终无颜色,而类型名、函数调用、宏、关键字有颜色。容易误判为"语义着色坏了",实际多数是认知偏差(见根因)。
• 变量先着色一瞬间,随即掉回无色,之后保持无色,不再恢复。
• 调整主题、修改着色规则、重置语言索引数据库均无效。

2. 根因

2.1 关键前提:局部变量 / 参数没有 TextMate 兜底

编辑器的着色有两层:语法语法(TextMate 语法)和语义着色(语言服务提供的 semantic token)。

• 类型名(尤其以约定后缀结尾的类型)、函数调用、宏、关键字、字符串、数字,TextMate 语法自带规则即可上色,与语义着色是否工作无关。
• 局部变量、函数参数没有任何 TextMate 规则能识别,只能由语义 token 上色。

因此"类型有色、局部变量无色"是常态,不能据此判断语义着色在工作。要判断语义着色是否真的在渲染,必须用编辑器自带的 token 检查器查看目标标识符是否带 “semantic token type” 信息。

2.2 并列原因对照

类型	失败机制
主题未给变量配色	语义 token 虽在,但当前主题没有为变量类 token 定义颜色,回退到默认前景色
语义着色未开启	editor.semanticHighlighting.enabled 默认 configuredByTheme;若主题未声明开启(或经 include 继承未生效),语义 token 不渲染
自定义规则 token 名写错	自定义着色规则用了通用名(如 variable),而该引擎实际发出的是带修饰符的名字(如 variable.local、parameter),规则不命中
提供器出 token 后清空	语言服务先返回 token(着色闪现),随后收到刷新请求重算时返回空,导致已渲染颜色被清除且不恢复;属于该扩展版本的缺陷
构建产物被反复重写	构建系统(CMake/Make 工具等)反复重新生成编译数据库,语言服务每次都重新解析翻译单元、清空已渲染 token

结论:先用检查器分清是"配色没配"还是"语义着色根本没渲染";若是后者且表现为"闪现即消失",需把问题定位到提供语义 token 的扩展版本,并降级到稳定版本。

3. 解决步骤

3.1 用 token 检查器定性(第一步,必做)

命令面板执行 Developer: Inspect Editor Tokens and Scopes,把光标放到一个无色的局部变量上,看弹框:

• 含 semantic token type: variable / modifiers: local 等行 → 语义着色在渲染,问题属"配色"(转 3.2)。
• 只有 standard token type 与 textmate scopes、无任何 semantic token 行 → 语义着色没在渲染或被清空(转 3.3)。

3.2 配色问题:不换主题就地给变量上色

在用户设置中加入以下内容(token 名以 3.1 检查器实际显示为准):

{
    "editor.semanticHighlighting.enabled": true,
    "editor.semanticTokenColorCustomizations": {
        "enabled": true,
        "rules": {
            "variable.local": "#9CDCFE",
            "variable.global": "#9CDCFE",
            "parameter": "#9CDCFE"
        }
    }
}

说明:

• 该类扩展使用标准语义 token 接口,局部变量为 token 类型 variable + 修饰符 local(选择器写 variable.local),全局变量为 variable.global,参数为 parameter。不要只写 variable,可能不命中。
• 显式设 editor.semanticHighlighting.enabled: true,避免依赖主题的 semanticHighlighting 标志(该标志经主题 include 继承时不一定可靠)。
• 改完需重新加载窗口(Developer: Reload Window)才生效;只重置语言索引数据库不会重新应用该开关。

3.3 语义 token 整体不渲染:隔离编辑器内核 vs 扩展(关键)

打开一个由独立语言服务提供语义着色的其他语言文件(例如 Python),观察其局部变量着色是否稳定:

• 其他语言稳定有色 → 编辑器内核、全局开关、自定义规则均正常,问题锁定在 C/C++ 扩展。
• 其他语言同样无色 / 同样闪掉 → 编辑器内核的语义着色回归,应降级或更换编辑器版本,而非动扩展。

排查时可一并排除以下非主线因素(均确认无关后再下结论):

- 是否存在第二个对 C 注册语义 token 提供器的扩展(多数语言扩展只管各自语言,通常无冲突)。
- 语言服务进程是否崩溃(查编辑器日志,无崩溃记录即排除)。
- 交叉/目标编译器探测是否成功(命令行执行该编译器的预定义宏导出,成功即排除)。
- 编译数据库是否包含目标源文件、是否被构建系统反复重写(监测其修改时间)。
- 语言服务的磁盘缓存是否损坏(清理后重启重建,仍旧即排除)。

3.4 确认为扩展版本缺陷:降级 C/C++ 扩展

当 3.3 判定为扩展专属、且表现为"着色闪现即消失",降级到上一个稳定版本:

1. 扩展面板(Ctrl+Shift+X)找到该 C/C++ 扩展。
2. 点其设置齿轮 → Install Specific Version / 安装特定版本。
3. 选低一档的版本(先试上一个次版本,仍旧再往下试)。
4. 重新加载窗口。

4. 验证清单

1. token 检查器对局部变量显示 semantic token type: variable 且带预期修饰符。
2. 局部变量、参数着色出现后持续稳定,滚动、切焦点后不掉色。
3. 同一规则对其他语言(如 Python)的变量着色一致生效,说明全局配置正确。
4. 重新加载窗口、重新打开文件后,着色仍稳定。

5. 维护要点

• 关闭该扩展的自动更新或锁定版本:否则下次自动升级会重新装回有缺陷的版本,问题复现。确认上游修复后再升级。
• 若问题由构建系统反复重配触发,关闭"打开工程即自动重新配置"一类选项,或让语言服务指向一份不被构建过程覆盖的编译数据库副本,避免反复重解析。
• 升级编辑器或该扩展后,回到第 4 节重新验证一次。

6. 备注

• token 检查器不显示基于编辑器装饰(decoration)的着色,只显示 TextMate scope 与标准 semantic token。若某扩展用装饰实现着色,检查器看不到属正常,需以实际界面为准。
• 以约定后缀结尾的类型名即使在语义着色完全关闭时也会被 TextMate 上色,易造成"语义着色仍在工作"的错觉,判断时以局部变量(无兜底)为准。
• 同机安装的其他语言扩展各自只对其语言注册语义 token,通常不会争抢 C 的着色,可不必逐一禁用。

7. 备选方案

7.1 更换语义着色引擎(稳健,代价是替换 IntelliSense)

改用独立的 C/C++ 语言服务(如 clangd):直接读取编译数据库,语义着色稳定,可绕开原扩展的着色缺陷。代价是 C/C++ 的 IntelliSense 整体改由新引擎提供;原扩展可保留用于调试等功能。适合原扩展所有版本都不稳定、或希望长期规避此类问题的情形。

7.2 关闭语义着色(不推荐)

{ "editor.semanticHighlighting.enabled": false }

缺点:会同时失去局部变量、参数的全部着色(它们没有 TextMate 兜底),与需求相悖。仅当无法接受闪烁、且不在意变量着色时作为临时手段。优先用第 3 节主方案(降级)或 7.1。

8. 其他工具 / 引擎的等价做法

更换为 clangd 后,自定义着色仍用 editor.semanticTokenColorCustomizations,clangd 使用标准 token 类型(variable、parameter 等),规则写法与 3.2 一致,但具体修饰符以 token 检查器实际显示为准。