Sublime Text 的 .sublime-syntax 文件必须严格遵循 YAML 规范、作用域命名惯例和 context 嵌套逻辑，缩进、字段格式、正则转义、作用域命名任一出错均导致语法完全失效且无提示；调试依赖重启+作用域查看+排除法。
Sublime Text 的 .sublime-syntax 文件不是“写完就能用”的配置，它必须满足 YAML 格式规范、作用域命名约定、嵌套层级逻辑，且需通过 sublime-syntax 解析器校验——任何缩进错误、未闭合的引号或非法作用域名都会导致整个语法完全不生效，连高亮 fallback 都不会触发。
YAML 格式和顶层字段不能出错
Sublime 的语法解析器对 YAML 极其严格：缩进必须用空格（不能混用 Tab），version 必须是 2.0，file_extensions 必须是列表（哪怕只有一个扩展名），scope 必须是合法的 CSS 类似作用域字符串（如 source.mylang）。
常见错误包括：
-
file_extensions: .ml（缺少方括号，应为file_extensions: [ml]） -
scope: source/mylang（斜杠非法，应为source.mylang） -
contexts:下直接写正则而没包在main:里
建议用 Sublime 自带的 Tools → Developer → New Syntax… 创建模板，再修改，避免手写顶层结构出错。
正则匹配必须加锚点和转义
Sublime 的 match 不默认行首/行尾锚定，^ 和 $ 在多行文本中行为与直觉不同；同时，反斜杠在 YAML 字符串中要双重转义。
例如想匹配 %% 开头的注释行：
match: '^%%.*$'
但实际需要写成：
match: '^%%.*$'
因为 YAML 单引号内反斜杠不转义，双引号内需写 \% 才能传给正则引擎。更稳妥的做法是用 begin/end 搭配 push 处理跨行结构，比如匹配多行字符串时：
-
begin匹配起始标记（如"""） -
end匹配结束标记（同样用"""） - 中间用
patterns嵌套处理转义、内联表达式等
作用域（scope）命名直接影响主题和命令行为
作用域不是随便起的标签，它决定了：ctrl+shift+p 中的“Go to Symbol”能否识别函数、代码折叠是否按 meta.function 触发、主题能否给 keyword.control 上色、甚至 LSP 插件是否向该 token 发送语义请求。
必须遵循社区惯例：
- 关键字用
keyword.control（if/for）、keyword.operator（==、+=） - 字符串内容用
string.quoted.double，而非string - 变量名统一用
variable.other.readwrite，函数调用用variable.function
错误示例：match: 'function' scope: 'function' —— 这个 function 作用域既不会被主流主题识别，也无法被 symbol_list 提取。
调试语法文件没有控制台，只能靠“排除法”
Sublime 不报语法文件加载失败的具体原因，只静默忽略。最有效的调试路径是：
- 保存后重启 Sublime（语法缓存在内存中，改了不重启无效）
- 打开一个目标文件，执行
Ctrl+Shift+P → “Show Scope Name”，把光标停在某段文字上，看底部状态栏显示的作用域是否符合预期 - 如果全是
text.plain，说明语法根本没加载成功，回去检查file_extensions和 YAML 格式 - 如果部分高亮异常，用
Ctrl+Alt+Shift+P（Windows/Linux）或Cmd+Alt+Shift+P（macOS）查看当前光标处完整作用域链，确认是否有意外的父级 context 覆盖了你的规则
真正难的不是写正则，而是理解 context 的栈式继承和 pop 行为——一个 pop: true 写错位置，就可能让后续所有匹配失效，而且毫无提示。
