Sublime Text 4+ 只支持 .sublime-syntax 文件，.tmLanguage 默认被忽略；旧版 ST3 需放 Packages/User/ 或插件目录；路径禁用空格和中文；正则需双转义；scope 必须以 source./text./meta. 开头且规范命名；调试用 Developer: Show Scope Name 查看真实 scope 链。
tmLanguage 文件到底该放哪
Sublime Text 4（含）之后只认 sublime-syntax，.tmLanguage 文件默认被忽略——不是你写错了，是它根本没加载。
- 旧版（ST3）还能用
.tmLanguage，但必须放在Packages/User/或插件专属目录下，不能放错层级 - ST4+ 强制要求转成 YAML 格式的
.sublime-syntax，直接扔.tmLanguage进去不会报错，也不会生效 - 路径中含空格或中文？Sublime 会静默跳过整个包，建议全用英文小写路径
正则写错一个反斜杠就高亮失效
tmLanguage / sublime-syntax 的 match 和 begin 字段全是 PCRE 正则，但 Sublime 内部做了两层转义：JSON 解析 + 正则引擎。你看到的 \ 实际传给正则的是单个 。
- 想匹配字面量
\\n（JSON 里\→，正则再收一个才能表示字面反斜杠） -
begin后没配end？整块内容会被吞掉，后续所有规则偏移，高亮全乱 - 用
(?i)忽略大小写可以，但别在captures里嵌套命名组——Sublime 不支持(?P<name>...)</name>
scope 名称不是随便起的
scope 决定颜色主题是否识别、能否被其他语法复用，比如 source.python 是 Python 主语法，variable.parameter.python 是参数变量。起名不规范，主题就找不到对应样式。
- 顶层 scope 必须以
source.、text.或meta.开头，否则 Sublime 直接拒载 - 避免用
keyword、string这类泛义词单独作 scope，应写成keyword.control.python或string.quoted.double.json - 自定义语法若想被 Markdown 嵌入（如代码块），需在
file_extensions里声明，并确保 scope 能被embed_scope正确捕获
调试时看不到真实 scope 链
按 Ctrl+Shift+P（Win/Linux）或 Cmd+Shift+P（macOS），输入 Developer: Show Scope Name，光标所在位置的完整 scope 链才显示出来——这是唯一靠谱的验证方式。
- 别信预览图或文档里的 scope 示例，实际继承链可能多出
meta.function.python这类中间层 - 如果点一下显示为空，说明当前文本没被任何语法规则捕获，大概率是正则没命中，或
include引错了文件 - 修改后必须重启 Sublime 或执行
Tools > Developer > Satisfy Dependencies（ST4+），否则缓存不刷新
真正卡住的地方，往往不是语法结构多复杂，而是路径没对上、scope 没写对前缀、或者以为自己在 ST3 写法里跑 ST4。
