Sublime Text插件必须放入Packages文件夹而非Installed Packages，路径因系统而异；插件目录名需规范，含正确.py文件及Sublime插件类；依赖、权限、重启或重载、控制台报错检查及命令面板验证是确保生效的关键步骤。
插件文件夹位置必须找对
Sublime Text 的 Packages 文件夹是插件实际存放地，不是 Installed Packages（后者只存 .sublime-package 压缩包）。手动安装必须把插件目录放进 Packages，否则 Sublime 根本不会扫描它。
路径取决于系统：
-
macOS：
~/Library/Application Support/Sublime Text/Packages/ - Windows：
%APPDATA%\Sublime Text\Packages\ - Linux：
~/.config/sublime-text/Packages/
注意：不同 Sublime 版本（如 Sublime Text 3 / 4）和安装方式（portable / system）可能导致路径微调，可在 Sublime 中通过 Preferences → Browse Packages… 直接打开正确文件夹。
插件目录结构要符合 Sublime 认可规范
Sublime 不接受任意命名的文件夹。插件主目录名最好与插件功能一致（比如 GitGutter），且内部至少包含一个 .py 文件，文件名需为 plugin_name.py 或 __init__.py（如果是包形式），且该文件中必须有继承自 sublime_plugin.TextCommand、sublime_plugin.EventListener 等的类。
常见错误：
- 把整个 GitHub 仓库 zip 解压后，把
repo-name-main/这层多余目录一起扔进Packages—— 应该只放里面真正的插件子目录 - 插件依赖
sublime_lib或其他模块，但没一并放入Packages，导致启动时报ImportError - 文件权限问题（尤其 Linux/macOS）：确保
.py文件有可读权限，否则 Sublime 加载失败且不报错
重启 Sublime 或手动重载插件
插件目录放好后，Sublime 不会自动发现新插件。有两种方式触发加载：
- 完全退出 Sublime Text 再重新打开（最稳妥）
- 在控制台（
Ctrl+`或Cmd+`）中执行：sublime_plugin.reload_plugin("YourPluginName")，其中YourPluginName是插件目录名（非文件名），注意大小写必须完全一致
如果重载后无反应或报错，打开控制台看是否有 ImportError、SyntaxError 或 AttributeError。典型提示如：
reloading plugin YourPluginName.plugin_name Traceback (most recent call last): File "plugin_name in …/Packages/YourPluginName.sublime-package", line 5, inImportError: No module named 'some_missing_dep'
调试插件是否生效的快速验证法
别等“功能看起来有没有用”，直接查 Sublime 是否识别到插件：
- 打开命令面板（
Cmd+Shift+P/Ctrl+Shift+P），输入插件名关键词，看对应命令是否出现 - 在 Python 控制台中运行：
import sublime_plugin [sublime_plugin.plugins() if p.name == 'YourPluginName' else None for p in sublime_plugin.plugins()]
—— 更简单的方式是检查sublime_plugin.plugins()返回列表里有没有你的插件实例 - 插件带菜单项？检查
Tools → Command Palette或右键菜单是否新增条目
很多插件需要特定文件类型（如只对 source.python 生效）或激活视图（比如当前文件必须已保存、有语法高亮），这些隐式前提常被忽略。
