离线安装插件失败主因是vscode静默校验、路径解析或版本匹配失败；拖拽需满足已加载工作区、窗口获焦点、文件为原始.vsix；cli未注册、架构不匹配、lsp依赖缺失亦致失效。
离线安装插件卡住，90% 不是文件损坏，而是 VSCode 在静默校验、路径解析或版本匹配环节直接放弃——它不报错，只“假装装上了”或者进度条停在 99% 不动。
拖拽 .vsix 文件后卡在 “Installing…” 或没反应
这不是插件问题，是 GUI 安装流程对环境状态极其敏感。它只在三个条件同时满足时才真正接收拖放信号：
- VSCode 必须已加载一个工作区（哪怕只是空文件夹），纯启动页或远程连接未建立时，拖放事件被忽略
- 主窗口要有系统焦点：任务栏图标高亮，且不能处于全屏、RDP/TeamViewer 远程桌面、或多显示器缩放偏移状态
- 拖入的是原始
.vsix文件，不是解压后的文件夹、不是.vsix.zip（浏览器下载常自动加后缀）、也不是右键重命名生成的双后缀文件
验证方法：unzip -l plugin.vsix 应显示顶层为 extension/ 目录，且含 extension/package.json。Windows 下路径含中文或空格？必须用英文双引号包裹，如 "C:/内网工具/ms-python.python-2024.6.0.vsix"。虚拟机共享文件夹（如 /mnt/hgfs）拖入常失败，先复制到本地路径（如 ~/Downloads/）再拖。
code --install-extension 命令无输出或报 command not found
这不是网络问题，是 CLI 工具根本没注册进系统 PATH。VSCode 官方 .deb/.rpm 包和 macOS ZIP 版默认不自动配置 code 命令。
- 先运行
which code：无输出就说明命令不可见 - 临时解决：用绝对路径，如
/usr/bin/code --install-extension /path/to/xxx.vsix（Linux）或/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code --install-extension /path/to/xxx.vsix（macOS） - 永久修复：在 VSCode 里按
Ctrl+Shift+P→ 输入Shell Command: Install 'code' command in PATH→ 回车执行，再重启终端 - 别加
sudo：否则插件会装到 root 用户目录，普通用户启动 VSCode 后看不到
装上了但插件没功能，比如 Python 无语法检查、Prettier 不格式化
这大概率不是插件没装上，而是语言服务器（LSP）没落地。像 ms-python.python、volarjs.volar、esbenp.prettier-vscode 这类插件，.vsix 只是前端壳，首次启用时才会联网下载 pyright-server、volar-server、prettier CLI 等 native 二进制依赖。
- 离线环境下，它就卡在 “Downloading…” 或直接静默跳过
- 正确做法：在有网机器上完整触发一次——打开一个
.py或.vue文件，等状态栏显示 “Ready” 后，把整个~/.vscode/extensions/ms-python.python-2024.6.0/目录（含子目录里的二进制文件）拷到内网机对应路径下 - 复制完必须彻底退出 VSCode，包括右下角托盘图标右键退出，否则缓存不刷新
报 Extension is corrupt 或 not compatible with the current version of VS Code
这不是文件损坏，而是 VSCode 在加载阶段拒绝解析 package.json 或校验失败。最常被忽略的是版本声明不匹配。
- 运行
code --version，取前两位（如1.92.2→1.92） - 解压
.vsix：unzip -p plugin.vsix extension/package.json | grep engines，看"vscode": "^1.85.0"这类字段 - 本地版本必须 ≥ 插件要求的最低版本；差一个小版本（如
1.92vs^1.93.0）就会静默拒绝 - ARM 架构机器（如 M-series Mac）不能装 x64 构建的
.vsix：Help → About 里看架构，再去 Marketplace 的versionhistory页面手动选对应平台旧版下载
复杂点在于：很多问题没有错误提示，只靠日志里几行 WARN 或 ERROR 定位，而这些日志分散在几百行中，人工翻极易漏。更麻烦的是，有些插件（如 C++）连 .vsix 都只是个下载器，真正干活的组件得靠首次激活触发——离线时这个动作根本走不通。
