离线安装VSCode调试扩展失败的根本原因是调试器二进制（如debugpy、OpenDebugAD7）未就位；需在联网机完整启用后复制整个解压后的扩展目录（含out/extension/debugpy等），并用code --install-extension xxx.vsix --allow-unverified安装。
离线安装 VSCode 调试扩展（如 ms-python.python、ms-vscode.cpptools、ms-dotnettools.csharp）本身不难，难在装完不能用——卡在 “Downloading debugpy”、“Starting OpenDebugAD7” 或 “Failed to launch adapter” 这类错误上。根本原因不是插件没装好，而是调试器二进制（debugger adapter）没到位。
拖拽 .vsix 到编辑区没反应？先确认三个硬条件
这是最常被忽略的“假失败”。VSCode 对环境状态极其敏感，缺一不可：
- VSCode 必须已加载工作区：哪怕只是
File → Open Folder…选一个空文件夹，不能停留在初始空白页 - 窗口要有系统焦点且未全屏：任务栏图标高亮，不能处于远程 SSH/Dev Container 连接中，也不能被 TeamViewer/RDP 缩放偏移干扰
- 拖的是原始
.vsix文件：不是解压后的文件夹，不是xxx.vsix.zip（Windows 右键重命名易生成双后缀），也不是 GitHub 上 clone 下来的源码目录
验证方法：unzip -l your-extension.vsix 应显示顶层为 extension/ 目录，且含 extension/package.json。
装上了却卡在 “Downloading debugpy”？那是 LSP + Adapter 分离架构导致的
像 ms-python.python 这类调试扩展，.vsix 只是外壳，真正干活的 debugpy、pyright、OpenDebugAD7 是首次启用时动态下载的独立二进制。离线时它不会报错，只会卡住或静默失败。
- 正确做法：在有网机器上完整走一遍流程——打开一个
.py文件 → 等状态栏 Python 图标变绿（表示debugpy和pylance均加载成功）→ 再把整个扩展目录（如$HOME/.vscode/extensions/ms-python.python-2024.6.0/）打包复制到离线机对应路径 - 别只拷
.vsix：必须复制解压后的完整文件夹，含node_modules/、out/和已下载的debugpy二进制（通常在out/extension/debugpy/或dist/下） - 注意版本对齐：
ms-python.python-2024.6.0依赖ms-python.debugpy-2024.6.0，查package.json的extensionDependencies字段最准
code --install-extension 报 INVALID_SIGNATURE 或静默失败？绕过签名验证是关键
离线环境无法校验微软证书链，VSCode 默认拒绝安装，但官方提供了明确绕过方式：
- 必须加
--allow-unverified参数：code --install-extension python.vsix --allow-unverified - 路径必须是绝对路径：Windows 推荐正斜杠+双引号，如
code --install-extension "C:/vsix/ms-python.python-2024.6.0.vsix" --allow-unverified；Linux/macOS 用/home/user/vsix/xxx.vsix - 装完必须彻底退出 VSCode：包括托盘进程（Windows 任务管理器结束所有
Code.exe，macOS 用killall -u $USER Code），否则缓存不刷新，新扩展不加载
企业内网批量部署调试扩展，别靠人肉拼链接
手动拼 Marketplace 下载链接极易出错（publisher、extension_name、version、targetPlatform 四者错一个就 404 或架构不匹配）。更稳的方式是：
- 在联网机器上用官方 CLI 工具：
vsce download ms-python.python@2024.6.0（需提前npm install -g vsce） - 或导出当前已配好的环境清单：
code --list-extensions --show-versions > extensions.txt，再逐行下载 - 依赖项不能漏：比如
ms-python.python强依赖ms-python.debugpy和ms-python.vscode-pylance，少一个，调试器就起不来
真正麻烦的从来不是“怎么装”，而是“怎么让调试器二进制在离线时就位”——这一步跳过，后面所有操作都只是在假装安装成功。
