插件无法加载的主因是路径结构错误、缺少plugin_loaded()函数、API版本不兼容或文件含BOM头；须将解压后关键文件直放Packages/对应子目录，定义空plugin_loaded()，适配ST4 API，并保存为无BOM的UTF-8编码。
插件文件放错目录导致 Package Control 无法识别
手动下载的插件 ZIP 或源码，不能直接解压到任意位置。Sublime Text 只会在特定路径下扫描插件，且要求结构合规。常见错误是把整个 ZIP 解压后扔进 Packages/ 目录，但里面还套了一层文件夹（比如 sublimetext-rainbow-brackets-master/），导致顶层缺少 .py 文件或 sublime-package 元数据。
正确做法是：
- 解压 ZIP 后，确认根目录下有
xxx.sublime-settings、main.py或xxx.sublime-commands等关键文件 - 将这些文件**直接放入**
Packages/对应子目录（如插件名叫RainbowBrackets，就新建Packages/RainbowBrackets/并把文件放进去） - 不要保留原始 ZIP 名中的版本后缀（如
-master、-v2.1.0），否则 Sublime 可能跳过加载 - Windows 路径示例：
%APPDATA%\Sublime Text\Packages\RainbowBrackets\；macOS：~/Library/Application Support/Sublime Text/Packages/RainbowBrackets/
plugin_loaded() 函数缺失或语法错误触发解析失败
Sublime Text 3+ 要求插件主 Python 文件必须定义 plugin_loaded() 函数（哪怕为空），否则会报 Unable to parse plugin 或直接静默失败。很多从旧版迁移或 GitHub 直接拷贝的代码遗漏了这个钩子。
检查你的 xxx.py 文件顶部附近是否包含：
def plugin_loaded():
pass
还要注意：
- Python 语法必须合法（比如缩进用空格而非 Tab 混用，没有中文标点）
- 不能在
plugin_loaded()外部执行可能抛异常的逻辑（如读取不存在的配置文件、调用未 import 的模块） - 如果用了
import，确保模块名拼写正确，且不在sublime或sublime_plugin之外引入不兼容的第三方库
插件依赖的 API 版本与当前 Sublime Text 不匹配
Sublime Text 4（Build 4122+）移除了部分旧 API，例如 view.change_count() 已废弃，改用 view.buffer_id() 配合 view.text_changed_events()；又如 sublime.RegionList 在 ST4 中不可直接实例化。这类改动会导致插件一加载就解析失败或崩溃。
判断方式：
- 打开
Console（Ctrl+`或Cmd+`），重载插件后看错误栈是否含AttributeError或NameError - 查看插件仓库的
README或issues，确认是否标注支持ST4 - 临时注释掉疑似新 API 调用，用
sublime.version()做运行时分支（例如if int(sublime.version()) >= 4122:）
文件编码或 BOM 头导致 Python 解析器报错
Windows 上用记事本保存的 .py 文件默认带 UTF-8 + BOM，而 Sublime Text 的 Python 解释器（基于 Python 3.3+）会把它当非法字符处理，报类似 SyntaxError: Non-UTF-8 code starting with '\xef' 的错误。
解决方法很简单：
- 用 Sublime Text 自身打开该
.py文件 → 菜单栏 File → Save with Encoding → UTF-8（不是 “UTF-8 with BOM”） - 或者用 VS Code / Notepad++ 等编辑器另存为无 BOM 的 UTF-8
- 检查文件开头是否有不可见字符：在 Sublime 中启用 View → Show Console，输入
view.substr(sublime.Region(0, 10))看前 10 字符是否含\ufeff
真正卡住的地方往往不是功能逻辑，而是路径层级、BOM、API 版本这三个隐性条件同时满足——少一个，plugin_loaded() 就不会被调用，插件也就永远“解析失败”。
