VSCode离线安装插件核心卡点是版本兼容、依赖完整、路径正确三者缺一不可；拖拽需在已加载工作区的主编辑区进行，code --install-extension报不兼容需比对package.json中engines.vscode与本地code --version版本。
VSCode离线安装插件不是“复制粘贴就能用”，核心卡点永远是版本兼容、依赖完整、安装路径正确——三者缺一不可。自动更新代码依赖在离线环境下根本不会发生，必须提前在有网机器上触发并打包。
拖拽安装没反应？先确认 VSCode 是否满足三个硬条件
VSCode 只在特定状态下响应拖拽：.vsix 文件必须拖进**已加载工作区的主编辑区域**（即你写代码的白底窗口），不是侧边栏、设置页或空白启动页。常见静默失败原因：
- VSCode 窗口没获得系统焦点（任务栏图标未高亮）
- 处于全屏模式或远程桌面（如 RDP/TeamViewer 会拦截拖放事件）
- 拖的是解压后的文件夹或重命名过的
.zip，不是原始.vsix包（可用unzip -l xxx.vsix检查顶层是否为extension/目录）
code --install-extension 报 “not compatible with Code” 怎么快速定位
这个报错几乎全是版本不匹配导致的，和网络无关。VSCode 安装时会严格比对 .vsix 内 extension/package.json 中的 "engines": {"vscode": "^1.80.0"} 字段与本地版本。实操步骤：
- 运行
code --version，取输出第一段（如1.85.2→1.85） - 用
unzip -p xxx.vsix extension/package.json | grep engines（Linux/macOS）或 7-Zip 打开查看该字段 - 确保本地版本 ≥ 插件要求的最低版本（
^1.80.0表示 ≥1.80.0 且 - ARM Mac 上装 x64 构建的插件（尤其含 native binary 的，如
pyright）也会触发同类报错，需找带darwin-arm64标识的版本
插件列表显示“已安装”，但 Python 补全/格式化不生效
这是离线环境最典型的假成功现象——安装通过了，但语言服务器或 CLI 工具没拉下来。关键点在于：
- 像
ms-python.python、esbenp.prettier-vscode这类插件，首次打开.py或.js文件时才会自动下载pyright、prettier等二进制依赖，默认走外网 - 离线时状态栏卡在 “Downloading…” 或输出面板报
Failed to fetch - 解决办法不是重装
.vsix，而是提前在有网机器上：打开对应文件类型 → 等状态栏变绿 → 再把整个扩展目录（如~/.vscode/extensions/ms-python.python-2024.6.0）完整拷到内网机器 - 不能只拷
.vsix文件，也不能只拷node_modules子目录——必须是解压后带package.json和out/或dist/的完整文件夹
手动复制到 extensions 目录的底层操作要点
当 GUI 和 CLI 都不可用（如纯终端服务器、权限受限环境），只能直投文件系统。但 VSCode 不接受 .vsix 文件本身，必须解压并严格对齐目录结构：
- 先用
unzip -l xxx.vsix查看顶层目录名，例如ms-python.python-2024.6.0/—— 这就是扩展 ID + 版本号，必须原样作为子目录名 - 解压后将整个文件夹移入用户
extensions目录：
Windows：%USERPROFILE%\AppData\Roaming\Code\Extensions\
macOS/Linux：$HOME/.vscode/extensions/ - 复制完必须彻底退出 VSCode（包括右下角托盘进程），否则缓存不刷新，日志里会出现
Extension 'xxx' is not installed - 重启后按
Ctrl+Shift+P输入Developer: Show Running Extensions，确认状态为Local而非Marketplace
真正容易被忽略的是：插件功能是否激活，和“是否出现在扩展列表”完全不是一回事；很多语言插件需要打开对应文件类型才加载，有些甚至要手动点击启用，而企业策略可能全局禁用扩展安装——这些细节不验证，就永远卡在“明明装了却不能用”的死循环里。
