GitLens功能失效主因是Git路径未正确配置或终端与GUI环境不一致；需在settings.json中手动设置"git.path"为绝对路径（如"C:/Program Files/Git/bin/git.exe"），并完全重启VSCode。
GitLens 是目前 VS Code 中最实用、最稳定的 Git 增强插件，但装上不等于能用——90% 的问题出在 Git 路径没配对、或终端与 GUI 环境不一致。
GitLens 安装后没反应？先确认 VS Code 能真正调用 git
VS Code 自身不带 Git，所有 Git 功能都依赖系统安装的 git 可执行文件。插件再强，找不到 git 就是白装。
- 在 VS Code 内置终端（
Ctrl + `）中运行git --version，必须有输出（如git version 2.40.1）；若报command not found，说明终端 PATH 没加载全，要检查 shell 配置文件（如~/.zshrc或~/.bash_profile）是否导出正确路径 - 按
Ctrl + Shift + P输入Git: Show Git Output，看输出面板里是否出现类似Using git 2.40.1 from /usr/bin/git的行；若显示Git not found或路径为空，说明 VS Code GUI 启动时根本没拿到 git - Windows 用户特别注意：
git.exe必须选C:/Program Files/Git/bin/git.exe，不是cmd/git.exe—— 后者缺 SSH 支持，推送到 GitHub/Gitee 时会在认证环节卡死
手动配置 git.path 是最稳的兜底方式
哪怕终端里 git 正常，VS Code GUI 启动时仍可能因环境变量继承问题找不到它。直接指定绝对路径，一劳永逸。
- 打开设置（
Ctrl + ,），搜索git.path - 点击「Edit in settings.json」，填入绝对路径，例如：
"git.path": "/opt/homebrew/bin/git"（macOS Homebrew）"git.path": "C:/Program Files/Git/bin/git.exe"（Windows，注意用正斜杠或双反斜杠） - 保存后必须完全退出 VS Code（关闭所有窗口）再重开，热重载不生效
GitLens 功能启用后，别误用左侧面板的 “+” 按钮
那个 “+” 图标不是 git add -A，它只添加「从未被跟踪过的文件」，已修改、已删除、已重命名的文件它统统忽略——这不是 bug，是设计行为。
- 想暂存所有修改：右键某个已修改文件 →
Stage Changes，或用命令面板（Ctrl + Shift + P）运行Git: Stage All - 想丢弃某段修改而非整个文件：在 SCM 视图中点开文件，hover 到改动行右侧，出现
⋯→Revert Selected Ranges - 提交时输入框支持多行，
Ctrl + Enter提交；勾选设置里的git.alwaysSignOff可自动加Signed-off-by
与其他 Git 插件共存时，优先禁用 Git Graph 和 Git History
GitLens 与 Git Graph、Git History 在底层都依赖相同 Git 数据源，同时启用容易引发 UI 渲染冲突、历史视图错乱、甚至导致 SCM 面板卡死。
- 如果发现 GitLens 的 blame 注释不更新、分支图谱空白、或右键菜单消失，先禁用其他 Git 类插件，仅保留 GitLens 测试
- GitLens 自带完整历史浏览（
Ctrl + Shift + P→GitLens: Open File Timeline）、可视化比较（右键 →Compare with Branch...）、分支图谱（GitLens: Open Repository Timeline），无需额外插件补足核心能力 - Git Graph 更适合偶尔查大图谱，日常开发中和 GitLens 同时开着，内存占用会明显上升，尤其在大型单体仓库中
GitLens 的真正门槛不在安装，而在理解它和系统 git 的绑定关系——路径配错、环境割裂、插件叠加，三者任一出问题，功能就断在第一环。调试时优先盯住 Git: Show Git Output 面板里的那行路径输出，比重启十次都管用。
