离线安装VSCode插件必须满足版本、架构、依赖、路径四重校验；code --install-extension报“not compatible”需手动比对code --version主版本号、package.json中engines.vscode字段及Help→About括号内架构标识，三者缺一不可。
离线安装 VSCode 插件不是“把 .vsix 文件拖进去就行”，而是必须满足版本、架构、依赖、路径四重校验，缺一不可；自动对比代码差异也不依赖插件，但触发条件和默认行为容易被误判。
code --install-extension 报 “not compatible with Code” 怎么快速定位
这个错误只说明不兼容，但不会告诉你哪里不匹配。得手动比三处：
- 运行
code --version，取主版本号（如1.90.2→1.90） - 用
unzip -p your-extension.vsix extension/package.json | grep engines查插件声明的"vscode": "^1.85.0"—— 表示最低需 1.85.0，你装 1.84.x 就直接跳过 - Help → About 里括号内容（
arm64/x64）必须和插件构建目标一致；ARM Mac 上装 x64 插件，可能连package.json都读不到
别信“差不多能用”，VSCode 对 engines.vscode 是硬性拦截，不报错、不提示，只是静默忽略加载。
拖拽 .vsix 到 VSCode 窗口没反应？先看这三点
图形界面安装失败，90% 不是插件问题，而是环境没达标：
- VSCode 必须已打开一个文件夹（即已加载工作区），纯空白窗口或远程 SSH 连接状态下拖放会被完全忽略
- 窗口要有系统焦点（任务栏图标高亮，且不能处于全屏模式）
- 拖的是原始
.vsix文件，不是重命名的（比如python.vsix.zip）、不是解压后的文件夹、也不是用右键“重命名”改后缀生成的（会损坏 ZIP 头）
验证是否原始文件：Linux/macOS 下运行 unzip -t python.vsix，显示 OK 才算完整；Windows 推荐用 PowerShell 执行 Copy-Item "old.zip" "new.vsix" -Force 生成新文件，而非重命名。
插件装上了，Python/ESLint/Rust 功能却不生效？缺的是 LSP 二进制
像 ms-python.python、dbaeumer.vscode-eslint 这类语言插件，离线安装只完成了“注册”，首次启用时才会下载 pyright、eslint CLI 或 rust-analyzer 等 native 依赖，默认走外网，结果卡在状态栏 “Downloading…” 或 Output 面板报 spawn ENOENT。
- 正确做法：在有网机器上，打开一个
.py文件 → 等pyright下载完成并稳定运行 → 关闭 VSCode → 拷整个插件目录（如ms-python.python-2024.6.0/）到内网机器对应extensions/目录下 - 不能只拷
.vsix，也不能只拷node_modules——pyright-server这类二进制藏在子目录里，漏一个就启动失败 - 验证方式：View → Output → 切换到 Python 或 ESLint 面板，看有没有
Failed to fetch或Cannot find module
Git: Open Changes 和 Compare with HEAD 不是一回事
很多人以为点右键 “Compare with HEAD” 就等于快捷键 Git: Open Changes，其实后者更智能、更可靠：
-
Git: Open Changes默认聚焦当前编辑器打开的文件，且只对比它与HEAD的差异；如果没打开文件，会弹出已修改文件列表供选，比翻源代码管理面板快得多 - 右键菜单里的 “Compare with HEAD” 实际调用的是
Git: Compare with Revision，但若当前文件未被 Git 跟踪（比如刚新建未git add），就会静默失败或比对空内容 - 真正容易被忽略的是 diff 视图左右侧含义：左侧是
HEAD（基准），右侧才是你的修改 —— 删了左边某段，意味着你要从历史版本里移除它，不是“还原”
离线环境尤其要注意：如果项目根目录下没有 .git 文件夹，Git: Open Changes 命令根本不会出现在命令面板里，不是快捷键失效，而是功能不可用。
