<p>新建Sublime语法文件必须用Tools→Developer→New Syntax…调用内置模板，避免手写.sublime-syntax时漏YAML头、缩进错位或字段拼错；name需设状态栏显示名，file_extensions须为YAML列表格式（如- xyz），scope必须以source.开头，保存路径严格为Packages/User/MyLang.sublime-syntax。</p>
新建语法文件必须用 Tools → Developer → New Syntax
手写 .sublime-syntax 容易漏掉 YAML 头、缩进错位或字段名拼错，直接导致静默失效。Sublime 内置模板已预置 name、scope、file_extensions 和 contexts 结构，改起来快且安全。
- 菜单路径是 Tools → Developer → New Syntax…，不是新建文本再改后缀
- 生成后立刻改
name（状态栏显示名）和file_extensions（如- myl），别留空数组 -
scope必须以source.开头，比如source.mylang；写成text.mylang或纯mylang就没颜色 - 保存时路径必须是
Packages/User/MyLang.sublime-syntax（大小写敏感，不能多一层目录，不能带空格）
扩展名绑定不生效？检查 file_extensions 格式和 Open all with current extension as…
file_extensions 字段只在语法文件里起作用，但 Sublime 不会自动“监听”你改了它——你得触发一次手动绑定，它才会把扩展名和语法路径写进用户设置。
- 确保
file_extensions是 YAML 列表格式：- xyz、- conf，不是["xyz", "conf"]也不是xyz, conf - 打开一个
.xyz文件（内容随意），点右下角当前语法 → Open all with current extension as… → 找到你的语法名（如User/MyLang） - 这步会自动生成
Packages/User/Preferences.sublime-settings里的extensions映射项，形如"syntaxes": [{"extensions": ["xyz"], "syntax": "Packages/User/MyLang.sublime-syntax"}] - 如果点开菜单找不到你的语法，说明文件没被加载：检查路径是否拼错、Sublime 是否重启过、有没有同名插件冲突
高亮规则写了却不生效？先看 Scope 是否被前置规则吞掉
正则没匹配上，90% 不是正则写错了，而是更早的 match 规则（比如字符串或注释）已经把目标文本捕获进别的 context，后续规则根本轮不到执行。
- 用
Ctrl+Shift+P→Inspect Scope，把光标停在未高亮的词上，看弹出的作用域是不是你写的（如keyword.control.mylang） - 如果显示
string.quoted.double，说明它被字符串规则吃掉了——把字符串match往下挪，关键字规则往上提 - 避免滥用
push:：进了新 context 后忘了pop: true，会导致整段代码卡在错误 context 里，后续全变白 - 测试阶段先删掉所有非必要规则，只留一条
match: '\bif\b'+scope: keyword.control，确认基础通路跑通再加复杂逻辑
default_syntax 配置只对 Ctrl+N 新建的 untitled 文件有效
想让所有新文件默认用 Python 语法？改 default_syntax 确实能办到，但它只影响「没保存、没路径、没扩展名」的空白标签页。一旦你保存为 .js 或打开已有 .env，这个配置就彻底失效。
- 正确验证方式：关掉所有窗口 → 新建窗口 → 按
Ctrl+N→ 看右下角是否直接显示你设的语言名（如Python），不是Plain Text - 值必须是完整语法路径，例如
"Packages/Python/Python.sublime-syntax"；用Show Scope Name查当前文件作用域，再把点换成斜杠、补Packages/前缀最稳 - 别指望它管
.conf或.env：这类文件靠扩展名匹配，得走file_extensions+Open all with current extension as…路线 - ST4 必须用
.sublime-syntax，写.tmLanguage路径不会报错，但就是不生效
实际调试时最容易卡住的地方，是以为改了语法文件就自动生效，结果没做手动绑定，或者 scope 名写错又没用 Inspect Scope 验证。Sublime 的加载机制很安静，不报错也不提醒，只能靠你主动查路径、查作用域、查用户设置里有没有生成映射项。
