离线安装GitLens等Git历史插件的核心难点是.vsix文件必须包含完整签名及GitLens Server二进制，且需在联网机预触发下载并拷贝整个扩展目录；直接安装.vsix常因缺少服务端依赖或签名验证失败导致功能缺失。
离线安装 VSCode 的版本对比与提交历史插件（如 gitlens、githd 或 vscode-git-history），核心难点不在“怎么装”，而在于**你手里的 .vsix 是否真能跑通 GitLSP 和本地 Git 二进制调用**——这类插件严重依赖运行时环境，离线装完不显示提交图、点开对比空白、右键菜单消失，90% 是因为漏了关键校验或依赖初始化。
gitlens.vsix 下载必须走官方直链，别碰 GitHub Release
GitLens 官方早已不再将完整 .vsix 发布到 GitHub Releases，那里的包通常缺失 GitLens Server（gitlens-server）二进制，导致离线环境下“能装不能用”。正确路径只有两个：
- 打开 https://www.php.cn/link/18c2faa8395ae875d9601ef1c6eb9e66 → 右侧 Resources → 点 Download Extension（生成带签名的临时直链）
- 拼 API URL：
https://marketplace.visualstudio.com/_apis/public/gallery/publishers/eamodio/vsextensions/gitlens/14.15.5/vspackage（注意：publisher 是eamodio，extension_name 是gitlens，version 必须和 Version History 页面里最新条目完全一致，比如14.15.5，不能写成14.15）
下载后建议重命名含平台标识，例如 gitlens-14.15.5-win32-x64.vsix，避免在 Windows 上误装 macOS 版。
code --install-extension gitlens.vsix --allow-unverified 是必加参数
离线环境无法连接微软证书链，不加 --allow-unverified 会卡在 INVALID_SIGNATURE 并静默失败。但光加这个还不够：
- 必须先关闭所有 VSCode 实例（包括托盘进程，Windows 可用任务管理器杀光
Code.exe） - 路径不能含中文或空格，例如
C:\vsix\gitlens.vsix安全，C:\用户\张三\vsix\gitlens.vsix会失败 - Windows 下推荐用正斜杠并加引号：
code --install-extension "C:/vsix/gitlens.vsix" --allow-unverified
装完没提交图？不是插件没装上，是 GitLens Server 没预触发
GitLens 在首次启用时才下载并启动自己的语言服务器（gitlens-server），离线环境卡在 “Loading…” 就是这个原因。正确做法：
- 在联网机器上完整触发一次：打开任意 Git 仓库 → 打开一个已提交的文件 → 右键选择
GitLens: Open File Timeline→ 等右下角状态栏出现GitLens Ready - 然后拷贝整个插件目录：
%USERPROFILE%\.vscode\extensions\eamodio.gitlens-14.15.5\（Windows）或~/.vscode/extensions/eamodio.gitlens-14.15.5/（macOS/Linux） - 粘贴到内网机对应路径下，**必须彻底退出 VSCode（含托盘）再重启**，否则缓存不刷新，旧的未初始化状态仍生效
git.history 插件（vscode-git-history）更轻量，但兼容性更脆
如果只需要看单文件提交历史，donjayamanne.githistory（现名 vscode-git-history）体积小、无服务端依赖，适合严格受限环境。但它对 VSCode 主版本极其敏感：
- 查看其
package.json中engines.vscode字段（解压 .vsix 后打开），例如"^1.84.0"表示只兼容 VSCode 1.84.x，装到 1.83 或 1.85 都会直接拒装 - 它不支持 Git Submodule 内的历史浏览，点进子模块文件会报错
Git: Not a git repository，这不是 bug，是设计限制 - 离线安装后若右键菜单无
Git: View History，先确认是否打开了 Git 仓库根目录（不是任意文件夹）
真正难的从来不是下载或安装命令，而是把 GitLens Server 这类运行时依赖提前“热起来”——它不像普通插件解压即用，而是需要一次真实 Git 操作来落地二进制和配置缓存。
