VSCode离线安装扩展必须严格满足版本匹配、文件完整、依赖齐备三条件：①拖拽.vsix前需已加载工作区、窗口有焦点且非全屏/远程状态；②用unzip -l校验文件结构，确保顶层为extension/目录；③语言类插件须在有网机启用后完整拷贝含LSP服务器的整个扩展目录。
“无法下载扩展”不是网络问题本身，而是 VSCode 拒绝加载插件的最终表现；真正卡住的地方通常是版本不匹配、文件损坏、或 LSP 依赖缺失——手动离线安装不是备选方案，而是必须按结构、版本、依赖三步走的刚性流程。
拖拽 .vsix 到主窗口没反应？先确认这三件事
这是最常被当成“失败”的假象，实际是环境未就绪：
- VSCode 必须已加载一个工作区（哪怕只是空文件夹），纯启动页或远程 SSH 未连接完成时拖放会被静默忽略
- 窗口必须有系统焦点：任务栏图标高亮，且不能处于全屏、RDP 或多显示器缩放偏移状态
- 拖的是原始
.vsix文件，不是解压后的文件夹、.zip、双后缀（如prettier.vsix.zip）或右键重命名生成的损坏包
验证方法：unzip -l your-extension.vsix 应显示顶层目录为 extension/，且含 extension/package.json；若报错或结构散乱，说明文件已损坏。
code --install-extension 报 “not compatible with Code” 怎么快速定位
这个错误只告诉你不兼容，但不会指出哪一环出问题。必须手动比对三处：
- 运行
code --version，取输出第一段（如1.85.2→1.85） - 解压
.vsix，查看extension/package.json中"engines": {"vscode": "^1.80.0"}字段 - Help → About 里括号中的架构（
arm64/x64）是否与插件构建目标一致（ARM Mac 装 x64 版本的pyright会静默失败）
注意：^1.80.0 表示最低要求 1.80.0，你本地是 1.79.2 就会被跳过——命令行会报错，GUI 拖拽则完全不提示。
插件列表显示“已安装”，但 Python/ESLint/Vue 补全不工作？大概率缺 LSP 服务
语言类插件（如 ms-python.python、dbaeumer.vscode-eslint、volarjs.volar）安装只是注册，首次启用才拉 native 依赖。离线时这些请求会卡在状态栏 “Downloading…” 或报 spawn ENOENT。
- 正确做法：在有网机器上完整走一遍流程——打开
.py/.vue文件 → 等状态栏变绿 → 确认 Output 面板中对应通道（如 Python）无报错 → 再拷整个扩展目录 - 路径要完整：
~/.vscode/extensions/ms-python.python-2024.6.0/（Linux/macOS）或%USERPROFILE%\AppData\Roaming\Code\Extensions\ms-python.python-2024.6.0\（Windows） - 不能只拷
.vsix，也不能只拷node_modules；pyright-server、volar-server-darwin-arm64这类二进制藏在子目录里，漏一个就启动失败
手动解压 .vsix 放入 extensions 目录为什么还是识别不到
VSCode 启动时扫描 extensions 目录，但只认严格符合结构的子目录：
- 先用
unzip -l your-extension.vsix查顶层目录名，例如ms-python.python-2024.6.0/—— 这就是扩展 ID + 版本号，必须原样作为子目录名 - 解压后整个文件夹（含
package.json、server/、node_modules/等）移入对应extensions路径 - 复制完必须彻底退出 VSCode（包括托盘进程），再重新打开；否则缓存不刷新，插件不会被加载
最易忽略的是：企业策略禁用时，GUI 和 CLI 都会失效，此时只能走解压直投，但必须确保外层目录名与 .vsix 内声明完全一致——差一个字符，VSCode 就当它不存在。
