VSCode插件安装失败主因是vscode版本不匹配、架构不符、工作区未加载、焦点缺失、文件非原始vsix、LSP未下载、策略限制或路径含空格，需逐项排查并彻底退出VSCode生效。
code --install-extension 报 “not compatible” 却不提示具体原因
这个错误几乎全是 engines.vscode 版本不匹配导致的静默拒绝，VSCode 不会告诉你差在哪一位。必须手动比对三处：
- 运行
code --version，取前两位（如1.92.2→1.92） - 用
unzip -p your.vsix extension/package.json | grep engines查"vscode": "^1.93.0"—— 你本地版本必须 ≥ 这个值 - Help → About 看架构（
x64/arm64），M 系列 Mac 装 x64 构建的 .vsix 会功能缺失，不是报错，是“装了但没反应”
拖拽 .vsix 后卡在 “Installing…” 或完全没反应
图形界面安装依赖后台网络校验和解压调度，断网时它不报错，只挂起或丢弃操作。真正生效需满足三个硬条件：
- VSCode 必须已加载一个工作区（哪怕只是空文件夹），纯启动页或远程连接未建立时，拖放事件被忽略
- 窗口要有系统焦点：任务栏图标高亮，且不能处于全屏、RDP、TeamViewer 或多显示器缩放偏移状态
- 拖的是原始
.vsix文件，不是解压后的目录、不是.zip、也不是右键重命名生成的xxx.vsix.zip（Windows 会静默解压）
插件列表里显示已安装，但 Python/Java/C++ 功能全失效
这不是插件没装上，而是语言服务器（LSP）没落地。比如 ms-python.python 只是前端壳，首次启用才下载 pyright-server；ms-vscode.cpptools 会尝试下载 C/C++ language components。离线环境卡在 “Downloading…” 就是这个原因。
- 正确做法：在有网机器上完整触发一次——打开一个
.py文件 → 等状态栏不再显示 “Downloading” → 再去%USERPROFILE%\.vscode\extensions\（Windows）或$HOME/.vscode/extensions/（macOS/Linux）里整个拷对应文件夹（如ms-python.python-2024.6.0/） - 不能只拷
.vsix，也不能只拷node_modules；native 二进制（如pyright-server）藏在子目录里，漏一个就启动失败 - 复制完必须彻底退出 VSCode（包括右下角托盘进程），否则缓存不刷新
企业策略禁用扩展或 CLI 命令不可用
某些内网环境启用了组策略，会直接屏蔽扩展市场或禁用 code 命令。这时候命令行报错或图形界面弹出 “Extensions disabled by policy”，就得绕过签名验证直装。
- 先确认是否策略限制：拖拽后右下角弹窗提示即为策略拦截，此时只能手动解压
- 手动解压路径：
unzip extension.vsix -d extension-unpacked→ 重命名为publishername.extensionname-version（如redhat.java-1.42.0）→ 移入用户extensions目录 - Windows 路径含中文或空格？命令行必须加英文双引号：
code --install-extension "C:\my ext\python.vsix"
