<p>Sublime Text 4 自定义语法需严格遵循路径、命名、scope、上下文顺序及 file_extensions 规范：必须置于 Packages/User/ 或插件目录，文件名以 .sublime-syntax 结尾且大小写敏感；scope 必须以 source. 开头并与主题兼容；match 规则按顺序执行，避免被前置规则吞没；file_extensions 必须为 YAML 列表格式（如 - xyz），修改后需手动重载语法定义。</p>
文件路径和命名必须严格匹配 Packages/User/ 目录结构
Sublime Text 4 不会扫描任意位置的 .sublime-syntax 文件，只认 Packages/User/（或插件专属目录如 Packages/MyPlugin/）下的合法文件。手误多建一层文件夹、用中文名、带空格或写成 mylang.syntax，都会导致静默失效。
- 正确路径示例：
Packages/User/mylang/mylang.sublime-syntax（Windows/macOS/Linux 均从此处开始，别写绝对路径） - 文件名必须以
.sublime-syntax结尾，且大小写敏感：MyLang.sublime-syntax可用，mylang.SUBTLE-SYNTAX或mylang.sublime-syntax.bak都无效 - 不能放在
Packages/User/MyLang/MyLang.sublime-syntax的子目录里——Sublime 不递归扫描
scope 值必须带 source. 前缀，且与主题兼容
写 scope: mylang 或 scope: text.mylang 是常见错误。Sublime 主题靠作用域链匹配样式，source.mylang 才是标准根 scope；否则即使规则匹配成功，也回落为纯白文本。
- 所有自定义 scope 应基于
source.mylang衍生，例如：keyword.control.mylang、string.quoted.double.mylang - 但注意：多数内置主题只定义了
keyword.control、string.quoted.double这类通用 scope，没加.mylang后缀。若想即刻生效，优先用通用名（如keyword.control），而非强行加后缀 - 如果坚持用
.mylang后缀，就得去改 color scheme 文件，手动添加对应 scope 的颜色定义——这步常被跳过
match 规则失效，90% 是上下文顺序或 scope 被吞掉
写了 match: '\b(if|else)\b' 却没高亮，大概率不是正则错了，而是更早的规则（比如字符串或注释）已把这段文本捕获，后续规则根本没机会执行。
-
contexts中规则按书写顺序匹配，字符串引号规则必须放在关键字规则之后，否则"if"整个被当字符串吃掉 - 用
Ctrl+Shift+P → Inspect Scope把光标停在目标词上，看弹出的 scope 是不是你写的（如keyword.control.mylang）。如果不是，说明没匹配上 - 避免用
push:进入新 context 后忘记pop: true或pop: 1，会导致后续文本全部卡在错误 context 里
file_extensions 绑定后缀必须用 YAML 列表格式
仅靠菜单里点一次 Open all with current extension as… 不持久——它只改当前会话。真正让 Sublime 自动识别 .xyz 文件，得靠语法文件里的 file_extensions 字段。
- 必须写成 YAML 列表：
file_extensions: [xyz, cfg]或换行写法：file_extensions:- xyz- cfg - 不能写成字符串：
file_extensions: "xyz"（解析失败） - 不能带点：
- .xyz错，- xyz对 - 改完保存后，要运行
Ctrl+Shift+P → Reload Syntax Definitions，或重启 Sublime——别等“自动重载”，它不总发生
实际调试时最易卡住的点，往往不在正则本身，而在 scope 名称是否被主题识别、上下文是否被意外截断、或是 YAML 缩进错了一格却没有任何报错提示。这些地方没有日志，只能靠 Inspect Scope 和反复删减规则来定位。
