离线安装GitLens需先下载对应VSCode版本和操作系统的.vsix文件，再用code --install-extension --allow-unverified命令安装；首次启用需联网缓存图标与元数据，否则blame等功能显示空白。
离线安装 Git 插件（如 GitLens 或官方 git 支持）本身不会直接“提高协作效率”，它只是让 VSCode 在无网环境下仍能调用本地 Git 命令、查看历史、比较分支——前提是你的项目已用 Git 初始化，且 git 命令行工具已在系统 PATH 中可用。真正卡住离线 Git 协作的，从来不是插件装不上，而是装上后不工作。
怎么确认你真正需要的是 GitLens 而不是内置 Git 支持
VSCode 自带基础 Git 集成（源代码管理侧边栏、提交/推送按钮），只要系统装了 Git 并配置好，这部分完全离线可用。而 GitLens 是增强型插件，提供 blame 内联、提交图谱、文件历史对比等功能——这些能力在离线时仍可运行，但首次启用可能触发网络请求（比如检查更新、加载图标 CDN）。若你只想要“右键看谁改了这行”，GitLens 是刚需；如果只是日常 commit/push，其实不用额外装插件。
- 检查是否已启用内置 Git：打开命令面板（
Ctrl+Shift+P），输入Git: Initialize Repository，能执行说明 Git 已就绪 -
GitLens的 ID 是eamodio.gitlens，不是git或vscode.git——后者是 VSCode 自带功能，无法也无需离线安装 - 企业内网常见误操作：把
Git History（另一个插件）和GitLens混用，结果两个都装却互相冲突，导致右键菜单失效
下载 .vsix 文件时最容易下错的三个地方
官网市场页的 “Download Extension” 按钮看似简单，但点错位置或版本就会导致安装静默失败。尤其 GitLens 更新频繁，2025.12.x 和 2026.6.x 对 VSCode 主版本要求不同。
CNB 云原生构建平台的 Git 操作技能，支持代码克隆、提交、推送、分支管理、Merge Request 管理、流水线触发与结果读取。初次使用需收集用户的 Git 用户名和邮箱。
- 必须进 https://www.php.cn/link/18c2faa8395ae875d9601ef1c6eb9e66，认准 publisher 是
eamodio，不是第三方镜像站或 GitHub Release - 右侧 Resources 区域的
Download Extension按钮只对当前最新版有效；如需旧版（例如适配 VSCode 1.78），得点开Version History，找对应条目再点下载 - 下载后立即重命名，加入平台标识，例如：
eamodio.gitlens-2026.6.2504-win32-x64.vsix——避免在 Windows 上误装 macOS 版本（后者解压后会缺.node二进制）
code --install-extension 安装失败的典型报错与解法
这个命令对环境极其敏感，报错信息极简，但原因明确。别猜，按顺序排查：
-
command not found: code→ 不是没装 VSCode，而是 Shell Command 未注册：在已启动的 VSCode 中按Ctrl+Shift+P，输入Shell Command: Install 'code' command in PATH并回车执行 -
INVALID_SIGNATURE→ 离线环境无法校验微软签名，必须加--allow-unverified参数：code --install-extension eamodio.gitlens-2026.6.2504.vsix --allow-unverified - 命令返回成功但插件不显示 → 90% 是 VSCode 还在后台运行：Windows 下打开任务管理器，结束所有
Code.exe进程；macOS/Linux 执行pkill -f "Code Helper"再重启 VSCode - 路径含中文或空格（如
C:\我的插件\gitlens.vsix）会静默失败，务必移至纯英文路径，如C:/vsix/gitlens.vsix，并用正斜杠 + 双引号包裹：code --install-extension "C:/vsix/gitlens.vsix"
装上了却看不到 blame 行号？那是 LSP 服务没落地
GitLens 不依赖语言服务器，但它的“当前行作者”“提交详情弹窗”等功能，首次启用时会尝试从 CDN 加载 SVG 图标和小量元数据。离线时这些请求超时，UI 就卡在空白或显示 loading。这不是插件坏了，而是资源没缓存。
- 解决方法：在有网机器上完整触发一次——打开任意 Git 仓库，打开一个已提交的文件，把光标停在某一行，等右键菜单出现
GitLens: Annotate with Git Blame并能点开为止 - 然后去该机器的
~/.vscode/extensions/eamodio.gitlens-2026.6.2504/目录，整个文件夹打包复制到内网机相同路径下 - 复制完必须彻底退出 VSCode（包括托盘进程），否则旧缓存不释放，新资源不加载
- 验证是否真生效：打开一个 .js 文件，右键某行，应立刻出现作者名+提交哈希，而不是转圈或报错
最常被忽略的一点：GitLens 的 engines.vscode 字段（在 package.json 里）必须和你的 VSCode 主版本号严格匹配，比如你用的是 1.82.2，就不能装要求 ^1.85.0 的版本——否则插件面板显示已启用，但所有功能按钮灰掉。
