插件必须放入Packages目录而非Installed Packages，解压GitHub ZIP后需移除多余层级并重命名文件夹，确保名称规范且含有效.py文件，重启需彻底终止进程，依赖模块须单独安装，目录名须与主模块名严格一致。
插件放错目录：Packages ≠ Installed Packages
手动安装失败最常见的原因是把插件文件夹丢进了错误的目录。Sublime 只扫描 Packages 目录下的 Python 文件夹，而 Installed Packages 是 Package Control 自动解压 .sublime-package 压缩包的地方——你往那儿拖文件夹，Sublime 根本看不见。
- 务必通过 Sublime 菜单进入：
Preferences → Browse Packages…，打开的才是正确路径 - Windows 路径示例：
%APPDATA%\Sublime Text\Packages\（注意不是 Sublime 安装目录） - macOS 路径示例：
~/Library/Application Support/Sublime Text/Packages/（不是Sublime Text 3或Sublime Text 4子目录，除非你明确用的是旧版） - Linux 路径示例：
~/.config/sublime-text/Packages/（ST4 默认用sublime-text，不是sublime-text-3）
下载 ZIP 后别直接扔整个 master 文件夹
GitHub 上点 Code → Download ZIP 得到的压缩包，解压后通常多出一层 plugin-name-main 或 plugin-name-master 目录。这层是 GitHub 自动生成的包装壳，不是插件本身——Sublime 加载时会找不到 .py 入口，控制台报 reloading plugin XXX failed 或完全静默失效。
- 解压后，进到那层多余目录里，把真正含
__init__.py或plugin_name.py的子文件夹单独拎出来 - 重命名为干净名称，例如把
BracketHighlighter-master改成BracketHighlighter - 确保名字不含空格、中文、点号（
.）或特殊符号，否则 Sublime 可能跳过加载 - 检查该文件夹内至少有一个
.py文件，且其中定义了继承自sublime_plugin.TextCommand等的类
重启不彻底 = 插件不生效
Sublime 不会在运行时自动扫描 Packages 新增目录。改完文件夹位置后只按 Ctrl+R 或关窗口再开是不够的——后台进程可能还在跑，插件根本没被加载。
- macOS：右键 Dock 图标 → Quit（不是关窗口），确认进程退出
- Windows：任务栏右键 → 任务管理器 → 结束所有
subl.exe进程 - Linux：终端执行
pkill -f "subl"或查ps aux | grep subl后kill - 验证方式：重启后打开命令面板
Ctrl+Shift+P，输入插件名看是否出现对应命令
遇到 ImportError 或控制台报错怎么办
插件启动时报 ImportError: No module named 'some_missing_dep'，说明它依赖其他模块（比如 sublime_lib），但你只装了主插件，没装依赖。
- 先去插件 GitHub 的
README.md或requirements.txt查依赖项 - 依赖本身也得手动安装：同样下 ZIP、解压、重命名、放进
Packages目录 - Linux/macOS 用户注意权限：
chmod +r *.py，否则 Sublime 读不到文件也不报错 - 如果控制台显示
SyntaxError，大概率是插件代码不兼容当前 ST 版本（如 ST4 用 Python 3.8+，某些老插件仍写print ""）
最常被忽略的一点：插件目录名必须和 Python 模块名一致，且大小写敏感。比如插件主文件是 gitgutter.py，目录就得叫 GitGutter 或 gitgutter，不能是 GitGutter-ST4 或 git-gutter——否则 sublime_plugin.reload_plugin("GitGutter-ST4") 会直接失败。
