GitGutter安装失败主因是Package Control未安装或失效，需先验证并重装；其次需确保系统已安装Git且文件位于Git仓库内；图标异常多因主题不兼容；性能卡顿可关闭live_mode改用on_save模式。
GitGutter 插件装不上？先确认 Package Control 是活的
Sublime Text 本身不带包管理器，GitGutter 必须通过 Package Control 安装——很多人卡在这步，不是插件有问题，是 Package Control 没装好或失效了。
检查方法：按 Ctrl+Shift+P（Windows/Linux）或 Cmd+Shift+P（macOS），输入 Package Control: List Packages。如果命令不存在，说明 Package Control 没装；如果存在但报错或无响应，大概率是网络或缓存问题。
- 重装
Package Control：去官网复制对应 Sublime 版本的安装代码，粘贴进 Sublime 的 Python 控制台（Ctrl+`）执行 - 国内用户常因 GitHub 资源加载慢导致安装失败，可临时改 hosts 或用代理；更稳的做法是等网络通畅时再试，别反复点“Install Package”
- 装完后重启 Sublime，再打开命令面板确认
Package Control: Install Package可用
安装 GitGutter 后没反应？检查 Git 路径和仓库状态
GitGutter 不是“装完就亮”，它依赖两个前提：系统能找到 git 命令，且当前文件在 Git 仓库里（或其子目录中）。
常见现象：插件装好了，但行号旁没出现 +/−/▶ 图标，状态栏也不显示分支名。
- 终端里运行
which git（macOS/Linux）或where git（Windows），确认路径；然后在 Sublime 中打开Preferences → Package Settings → GitGutter → Settings，把"git_binary"设为绝对路径，比如"/usr/local/bin/git"或"C:\Program Files\Git\bin\git.exe" - 确保当前打开的文件属于某个 Git 仓库：终端进该目录，执行
git status应有输出；如果文件在未git init的文件夹里，GitGutter 就不会工作 - Sublime 默认只监控当前视图（tab）所在文件的仓库，跨项目多根文件夹（如用
Project → Add Folder to Project）时，每个文件夹需各自是 Git 仓库，否则只认第一个
图标颜色/位置不对？别乱改 settings，先看主题兼容性
GitGutter 的 +/−/▶ 图标本质是靠 Sublime 主题里的 gutter 区域渲染的，不是所有主题都默认支持它的高亮样式。
典型表现：图标挤成一团、颜色全灰、或者根本看不见，但日志里又没报错。
- 先换回 Sublime 默认主题（
Preferences → Theme → Default.sublime-theme），看是否恢复正常——如果恢复了，就是你当前主题没适配 GitGutter 的 gutter key - 不要手动修改
gutter_padding或gutter_icons等设置来“强行对齐”，这容易引发缩放错位，尤其在高 DPI 屏幕上 - 想自定义图标，只建议改
"icon_path"指向自己准备好的 PNG/SVG（注意尺寸必须是 16×16 或 32×32），别碰"icon_position"，这个值由主题控制，硬设反而失效
实时更新延迟或卡顿？关掉不用的刷新策略
GitGutter 默认每 500ms 调一次 git status 和 git diff，小项目没问题，但一旦项目含大二进制文件、忽略规则复杂，或 .git 在远程挂载盘上，就会明显卡顿、CPU 占用高。
- 打开
GitGutter.sublime-settings，把"live_mode"设为false，改用"on_save"模式：只在保存时刷新，适合大多数本地开发场景 - 如果连保存都慢，加一条
"ignore_files"，填正则匹配不需要比对的路径，比如"node_modules/.*|dist/.*|\.log$" - 避免在大型 monorepo 根目录开整个项目——GitGutter 会递归扫描所有子目录的 .git，改成只打开具体子包文件夹，性能提升明显
真正麻烦的是混合使用符号链接的仓库，或者 .git 文件被移动过（比如从 submodule 拉出来单独用），这种时候 GitGutter 往往静默失败，得手动检查 git rev-parse --git-dir 输出是否合理。
