离线安装 GitLens 前须先确认系统已安装 Git 并加入 PATH，下载 vsix 时必须指定 targetPlatform 参数，安装须用 code --install-extension 命令，且仅在已识别的 Git 仓库中激活功能。
离线安装 GitLens 前必须确认 Git 是否可用
GitLens 启动时会立即调用 git 命令检查仓库状态，如果终端里执行 git --version 报错 command not found: git，插件装上也白装——根本不会激活。这不是 GitLens 的 bug，是设计逻辑：它不自带 Git，只依赖系统已安装的 Git 二进制。
所以离线安装前，请先在目标机器上验证：
- 打开 VS Code 内置终端（
Ctrl+`），输入git --version，应返回类似git version 2.40.1 - 若失败，需手动安装 Git 并确保其路径加入系统
PATH（Windows 推荐勾选 “Add Git to PATH” 安装选项） - VS Code 设置中检查
git.path是否指向正确路径，例如"git.path": "C:\Program Files\Git\bin\git.exe"
下载 vsix 文件时必须带 targetPlatform 参数
直接从 Marketplace 页面点 “Download Extension” 按钮，下载的 vsix 往往是通用版或平台不匹配，尤其在 macOS Apple Silicon 或 Windows ARM 设备上静默失效。你得手动构造带平台标识的下载链接。
以最新稳定版 2025.12.2504 为例，Windows x64 用户必须用：
https://marketplace.visualstudio.com/_apis/public/gallery/publishers/eamodio/vsextensions/gitlens/2025.12.2504/vspackage?targetPlatform=win32-x64
macOS Intel 用户则用 darwin-x64，Apple Silicon 用 darwin-arm64。漏掉 ?targetPlatform=xxx 或写错，会导致插件安装后无法加载，且无明确报错提示。
验证下载文件是否匹配：解压 .vsix（改后缀为 .zip 即可），打开 package.json，检查 engines.vscode 版本是否兼容你的 VS Code（如 ^1.80.0 要求 VS Code ≥1.80），并确认 platform 字段（如有）与目标一致。
GInstall OneClick — 一键安装 GitHub 项目：规划、克隆、安装 Node 依赖、运行开发脚本。适用于想要获取 GitHubNode.js 项目的用户。
安装命令必须用 code --install-extension 且路径要绝对
别把 .vsix 文件拖进 VS Code 窗口，也别复制到 .vscode/extensions 目录下手动解压——VS Code 不认这种操作，插件不会出现在扩展列表里。
正确做法是通过命令行运行安装命令：
- 确保
code命令已加入系统环境变量（Windows 可在 VS Code 中按Ctrl+Shift+P输入Shell Command: Install 'code' command in PATH来修复） - 进入 .vsix 所在目录，执行：
code --install-extension eamodio.gitlens-2025.12.2504.vsix - 如果路径含空格或中文，务必用英文引号包裹完整路径：
code --install-extension "D:dev oolseamodio.gitlens-2025.12.2504.vsix" - 安装成功后终端会输出
Extension 'eamodio.gitlens' was successfully installed.，无需重启 VS Code
装完没反应？重点查插件激活状态和右键菜单
GitLens 安装后不会自动弹窗、不改界面布局，很多人误以为“没装上”。实际它靠上下文触发：只有在 Git 仓库内打开文件，右键才有 GitLens: Show Line History 等选项；光标悬停在代码行左侧空白处，才会显示 blame 注释。
快速验证是否激活：
- 打开一个已
git init或克隆的项目文件 - 按
Ctrl+Shift+P输入GitLens: Toggle File Blame Annotations，回车——如果出现行首 commit 信息，说明已正常工作 - 若提示 “command 'gitlens.toggleFileBlameAnnotations' not found”，大概率是 Git 未就绪，或插件版本与 VS Code 不兼容（比如用了要求 1.90+ 的插件，但本地是 1.78）
- 检查 VS Code 左下角状态栏是否有 Git 分支名显示，没有则 Git 未识别仓库，GitLens 也不会启动
真正容易被忽略的是：GitLens 的功能深度绑定 Git 仓库结构。它不是“装完就能看历史”，而是“有 Git 提交记录 + 当前文件在仓库中 + VS Code 正确识别该仓库”，三者缺一不可。内网环境常因 .git 目录权限、符号链接或子模块路径异常导致识别失败，这时 blame 和 history 都会静默不响应。
