VS Code代码高亮插件本质是基于TextMate语法定义的声明式配置，依赖tmLanguage.json文件中的正则、scope命名和嵌套规则，而非JavaScript运行时逻辑；scope名须严格匹配package.json中contributes.grammars[0].scopeName，且需正确配置contributes.languages与activationEvents，调试依赖Developer: Inspect Editor Tokens命令验证scope链。
代码高亮插件本质是 TextMate 语法定义
VS Code 的代码高亮不靠 JavaScript 运行时逻辑，而是基于 tmLanguage.json（或 .tmLanguage）文件驱动的 TextMate 语法规则。这意味着你写的“高亮插件”实际是一组正则匹配 + 范围嵌套 + scope 命名的声明式配置，不是运行时动态判断。写错 scope 名、漏掉 repository 引用、或正则未转义特殊字符，都会导致高亮完全失效，且无报错提示——只会静默不生效。
常见错误现象包括：关键字没变色、注释被截断、字符串内嵌变量不突出、整段代码灰成一片。这些几乎全是语法文件结构或 scope 命名问题，跟 extension.ts 无关。
- scope 名必须符合
source.xxx或text.xxx前缀规范，例如source.python、text.html.basic - 所有嵌套规则（如字符串内的转义序列）必须通过
include或push显式引用repository中定义的片段，不能直接写在patterns里 - 正则中
.、*、?、(等需用反斜杠转义，否则会被 TextMate 解析器误读 - scope 名要与
package.json中contributes.grammars[0].scopeName完全一致，大小写敏感
package.json 必须正确声明 grammar 和 language
即使语法文件写对了，package.json 配置错一步，VS Code 就根本不会加载它。最关键的两个字段是 contributes.grammars 和 contributes.languages，它们分工明确、缺一不可：
-
contributes.languages告诉 VS Code：“这是一种新语言”，并绑定文件扩展名（如.foo）和语言 ID（如foo-lang） -
contributes.grammars告诉 VS Code：“这个语言用哪份语法文件渲染”，必须指向tmLanguage.json，且scopeName必须和语法文件根节点的scopeName完全一致 - 如果只配 grammar 不配 language，VS Code 不知道该对什么文件启用它；如果只配 language 不配 grammar，VS Code 会 fallback 到纯文本模式
- language ID（如
foo-lang）还要在activationEvents中声明onLanguage:foo-lang，否则插件不会自动激活
调试高亮失效：用 Developer: Inspect Editor Tokens
VS Code 内置的 Developer: Inspect Editor Tokens 命令（Ctrl+Shift+P 输入执行）是唯一可靠的调试手段。它能实时显示光标处文本的实际 scope 链，比如：keyword.control.foo-lang → source.foo-lang。如果看到的是 source.plain.text 或空 scope，说明 grammar 没生效；如果 scope 名拼错（如 source.foo_lang），就说明 scopeName 不一致。
注意：这个面板不显示正则是否匹配成功，只显示最终应用的 scope。所以必须先确认 scope 链正确，再检查语法文件里对应 scope 的规则是否写错。
- 打开一个目标文件（如
test.foo），确保其 language mode 已设为你的语言 ID（右下角点击切换） - 把光标停在想高亮的词上，执行
Developer: Inspect Editor Tokens - 看 “Scope” 列是否出现你定义的 scope，以及是否被更外层 scope 覆盖（如
comment.line优先级高于keyword） - 如果 scope 正确但颜色不对，问题出在主题（theme）未映射该 scope，不是插件问题
scope 命名影响主题兼容性，不是随便起的
VS Code 主题（如 One Dark Pro、GitHub Dark）只预设了有限的 scope 映射，比如 keyword、string、comment。如果你定义的 scope 是 keyword.custom-foo，而主题没配它，那它就按默认色显示（通常是前景色）。真正起作用的是 scope 的「语义层级」，不是名字长短。
- 优先复用标准 scope，如
keyword.control（控制关键字）、entity.name.function（函数名）、support.type（内置类型） - 避免自创顶层 scope（如
custom-foo），应基于已有前缀扩展，如keyword.control.foo-lang - scope 越长，匹配优先级越高，但主题支持越差；越短（如
keyword），主题适配越好，但容易被其他规则覆盖 - 测试时务必换几个主流主题，确认关键元素在不同主题下都有合理颜色，而不是只在某个主题下“看起来对”
最常被忽略的一点：语法文件里的 scopeName 和 package.json 里的 scopeName 必须逐字符一致，包括大小写、连字符、点号——VS Code 不做 normalize，错一个字符就彻底失效。
