不少开发者在 Atom 里装了 minimap-git-diff 插件，满心期待能看到红色绿色的差异标记，结果缩略图一片空白，除了代码啥都没有。其实问题往往不在插件本身，而在于 Git 的状态和文件路径没对上。
minimap-git-diff 装了但没显示差异色块？先确认 Git 状态和文件路径
插件的工作方式很直白——它只渲染 git diff --cached 和工作区里那些未暂存的改动。如果当前文件压根没被 Git 跟踪，或者在工作区里没做过修改，又或者文件路径根本不在当前仓库的根目录下面，那缩略图自然什么都不标。最常见的情况是：明明改了代码，minimap 右侧却一片灰，怎么看都像是插件失灵了。
- 用终端跑一下
git status，确认文件出现在 “modified:” 列表里 - 检查 Atom 当前项目的根目录是否等于 Git 仓库的根目录（可以用
git rev-parse --show-toplevel验证），否则插件找不到 .git 目录，会直接放弃渲染 - 无扩展名的文件，或者右下角显示
Plain Text的，minimap-git-diff不会生效，必须手动切换语言模式 - 二进制文件（比如
.png）或者含非法 BOM 的 UTF-16 文件也会被跳过——不报错，不提示，直接静默忽略
为什么只显示绿色/红色块，却不标具体哪行改了？
这是个很容易让人困惑的点。minimap-git-diff 默认只画区块轮廓，并不映射到精确的行号。它依赖的是 git diff 输出的 hunk 起始行加上行数估算的位置，而不是逐行比对。所以在滚动的时候，颜色块可能会偏移 1～2 行，尤其是在长文件或者混合宽字符（比如 emoji、中文）的场景下，偏差会更明显。
- 记得确保
minimap-plus里的Click to move cursor是开启的，否则点色块跳不过去 - 不要同时启用
minimap-cursorline和minimap-highlight-selected——它们会覆盖minimap-git-diff的颜色层，导致色块变淡甚至消失 - 把
minimap-plus的Contrast调到 0.9 左右，Opacity调到 0.98，否则浅绿浅红在暗色主题下几乎看不见 - Git 暂存区为空的时候，只显示未暂存的改动；执行
git add -u之后，色块会从红色（unstaged）变成绿色（staged）
和其他 minimap 插件共存时样式打架怎么办？
多个插件往同一个 DOM 元素里注入样式，冲突是常有的事。最常见的是 minimap-highlight-selected 和 minimap-git-diff 打架——前者高亮选中区域，后者高亮 Git 变更，但两者都操作 .minimap-selection 类，最后谁后加载谁就赢。
- 优先禁用
minimap-cursorline：它和minimap-highlight-selected功能重复，而且默认样式权重更高，经常把 Git 色块压掉 - 如果非要同时保留高亮和 diff，进
minimap-highlight-selected的设置页，把Highlight selected text关掉，只留Highlight current line - 所有 minimap 衍生插件（比如
minimap-bookmarks、minimap-find-and-replace）建议按需启用，开得越多，主线程渲染压力越大，色块响应延迟越明显 - 大文件（超过 5000 行）下，
minimap-git-diff的渲染会降帧来保主编辑器流畅——这不是 bug，是 Atom 的 DOM 架构限制
apm install minimap-git-diff 后仍报错或加载失败？
错误通常出在依赖链或者 Node.js 版本错配，尤其是 Atom 1.60+ 的用户。原版的 minimap-git-diff 已经停止维护了，所以必须用适配分支。
- 别装
minimap-git-diff原包，改用minimap-plus-git-diff（它是minimap-plus官方推荐的配套）：apm install minimap-plus-git-diff - 装完之后检查
~/.atom/packages/minimap-plus-git-diff/package.json，确认"engines": {"atom": ">=1.58.0"}和你当前的 Atom 版本匹配 - Windows 用户如果遇到
node-gyp编译失败，先运行npm install -g windows-build-tools再重试 - 离线安装时，记得进插件目录执行
apm install（不是npm install），否则模块路径不对，Atom 找不到插件入口
真正容易被忽略的是：minimap-git-diff 的渲染完全依赖 Git 仓库状态和 Atom 对文件类型的判定，而不是“你刚保存了文件”这个动作。哪怕只是路径多了一层 ../，或者文件编码用了 UTF-16 LE，它就会静默退出，不提示、不报错、也不 fallback。
