Sublime-completions 文件不生效最常见原因是文件名或路径错误。必须为 xxx.sublime-completions 后缀，置于对应系统 User 包目录，且文件名不含空格、中文或特殊符号。

为什么 sublime-completions 文件不生效？

最常见原因是文件名或路径不对。Sublime Text 要求补全定义必须是 xxx.sublime-completions 后缀，且放在正确目录下：
– Windows：%APPDATA%\Sublime Text\Packages\User\
– macOS：~/Library/Application Support/Sublime Text/Packages/User/
– Linux：~/.config/sublime-text/Packages/User/
文件名不能

如何写一个有效的 .sublime-completions 文件？

它本质是 JSON，但结构有硬性要求：顶层必须是 "scope" + "completions" 两个字段。"scope" 控制触发场景（比如只在 Python 中生效），"completions" 是数组，每个元素是一个补全项对象。

{
  "scope": "source.python",
  "completions": [
    {
      "trigger": "req",
      "contents": "requests.get('${1:url}', headers=${2:headers})"
    },
    {
      "trigger": "logd",
      "contents": "logging.debug('${1:message}')"
    }
  ]
}

注意：
– "trigger" 是你输入后按 Tab 或 Enter 触发的关键词
– "contents" 支持占位符 ${1}、${2} 实现跳转编辑
– 不要加 "file_extensions" 字段——那是旧版 Sublime 2 的写法，已废弃

怎样让自定义补全优先于插件补全？

Sublime 默认按“作用域匹配精度”和“加载顺序”决定优先级。想压过插件（比如 Python Completions），关键在 "scope" 值更具体：

• 用 source.python meta.function-call.python 比 source.python 更精准，只在函数调用位置生效
• 避免宽泛 scope 如 text.plain，否则可能干扰其他语法高亮
• 如果多个 .sublime-completions 文件 scope 完全一致，加载顺序取决于文件名 ASCII 序（a.sublime-completions 早于 b.sublime-completions）

调试建议：打开 Ctrl+` 控制台，输入 view.scope_name(view.sel()[0].begin()) 查看当前光标处的实际 scope。

补全卡顿或响应慢怎么办？

大文件或低效正则会拖慢自动补全。Sublime 的补全引擎对以下情况敏感：

• 单个 .sublime-completions 文件超过 500 条 "completions"，建议拆分（如按模块分 django.sublime-completions、flask.sublime-completions）
• 避免在 "trigger" 中使用正则（Sublime 不支持 trigger 正则匹配）
• 禁用冲突插件：某些代码提示插件（如 AutoFileName）会劫持补全事件，可临时关闭测试
• 确保没有重复定义相同 "trigger" 的多个文件，否则每次补全都要遍历所有匹配项

真实场景中，补全延迟往往不是因为“功能没开”，而是 scope 冲突或文件体积失控——先查控制台报错，再删一半补全项做二分排查。