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...)

scope 名称不是随便起的

scope 决定颜色主题是否识别、能否被其他语法复用，比如 source.python 是 Python 主语法，variable.parameter.python 是参数变量。起名不规范，主题就找不到对应样式。

Twain

一款专注于沟通场景的AI写作助手，可帮助用户改进销售邮件和消息表达，让沟通内容更加清晰自然。

下载

• 顶层 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。