客户现场的机器不通外网，扩展面板里搜 Python 一直转圈，最后报一个 XHR failed。带过去的 vsix 装完，又提示扩展与当前版本不兼容。

先分清装在哪一端

用 Remote 连服务器开发时，扩展分本地和远端两份。Python、C++ 这类要在远端跑，得在 SSH 连接的窗口里装，本地装了不起作用。判断方法看扩展详情页的安装按钮，通常有本地和远程两处，选错是最常见的坑。

拿到 vsix 的两条路

联网机器上直接下：扩展详情页右侧的齿轮菜单里有下载 VSIX 的选项。也可以用命令行装一遍，然后到用户目录的 .vscode/extensions 里把整个文件夹拷走，注意连版本号一起带，插件更新后目录名会变。

  • code --install-extension ms-python.python
  • code --install-extension ./python-2024.vsix

不兼容的报错怎么读

提示扩展与当前 VS Code 不兼容，一般是对面要求的 engines 版本高于你的。两条路：升级本地 VS Code，或者在市场页面右侧的版本历史里挑发布时间早一点的 vsix。硬改包里的 package.json 也许能装上，运行时常报找不到 API，不建议省这一步。

依赖插件容易漏

有些扩展是壳，真正干活的是它依赖的另一个包，比如 C# 系列要 .NET 运行时，Jupyter 相关要配套的 kernel 扩展。离线环境只能看详情页的依赖列表，一个个下。装完在扩展面板确认没有黄色感叹号，再重启窗口。批量部署的，把 vsix 和安装命令写进一个脚本，按顺序执行。

装完不生效，先看扩展主机日志

装上了但功能没出来，多半是没重载窗口，或者扩展在远端但本地开的文件。命令面板里搜「开发人员: 显示扩展主机日志」，能看到加载失败的原因，常见的是找不到运行时、权限被策略拦下。企业环境还有白名单机制，扩展目录被策略锁成只读，装进去也会被清掉，这种情况得让 IT 放开目录。

结论：先分清本地还是远端，再按引擎版本挑 vsix，依赖列成清单一次带全。