VS Code 远程环境装不上扩展、更新卡住：本地与远端两条下载链路怎么分开查

远程环境装不上扩展，先分清是哪一条链路在下载

在本机上用 VS Code，扩展安装失败通常只需要看本机网络；但一旦用 Remote-SSH 连到远端主机，情况就复杂了：编辑器界面在本地，扩展和 VS Code Server 却运行在远端，下载动作到底发生在哪一边，直接决定了你该去修哪条链路。本文不重复「市场下载慢」这类泛泛的说法（那部分可以看VS Code 扩展市场下载慢或安装失败的排查），而是专门讲远程场景里，扩展安装失败、更新一直转圈时，怎么把本地和远端两条下载链路分开检查。文中的设置项来自 VS Code 官方文档，查阅时间为 2026 年 10 月，界面可能随版本变化。

两条链路：本地下载与远端下载分别负责什么

VS Code Server 是谁下载的

官方 Remote-SSH 文档说明，首次连接时扩展会在远端系统上安装 VS Code Server，它独立于远端已有的任何 VS Code 安装。相关设置 remote.SSH.localServerDownload 控制下载位置：默认的 auto 会先尝试在远端下载，远端没有外网时回退为本地下载后经 SSH 连接传输；always 强制本地下载再传输；off 则只尝试远端下载。文档同时指出，安装与更新服务端要求本地机器具备出站 HTTPS（443 端口）连接。

扩展是在哪一端安装的

在 Remote-SSH 会话里，部分扩展安装在远端，由远端环境去访问扩展市场；远端是内网机器、没有外网出口时，这类安装会失败或一直转圈。这时候界面上的提示常常很含糊，所以要用后面的办法单独验证远端的出站能力，而不是在本机反复重试。

怎么确认远端到底有没有外网

直接登录远端终端，运行 curl -sS -o /dev/null -w "%{http_code} %{time_connect}\n" https://marketplace.visualstudio.com，看能否拿到状态码以及连接耗时。官方网络文档列出了需要放行的主机名，包括 marketplace.visualstudio.com、*.gallery.vsassets.io、*.gallerycdn.vsassets.io、*.vscode-unpkg.net 和 download.visualstudio.microsoft.com。远端网络设有出站访问限制时，这几个域名是第一批要核对的。

用 VSIX 离线安装绕开远端下载

远端没有外网时，最稳妥的办法是在本地准备好扩展包，再手动装到远端。官方扩展管理文档支持从 VSIX 安装，既可以在命令面板运行「Extensions: Install from VSIX」，也可以用命令行：

# 先把扩展包传到远端
scp ./some-extension.vsix dev-box:/tmp/
# 在远端终端安装
code --install-extension /tmp/some-extension.vsix

示例里的文件名与主机别名只是占位。要注意文档里的一条说明：通过 VSIX 安装的扩展，默认会关闭自动更新，所以后续升级需要你自己下载新版 VSIX 再装一次。如果主机是经跳板机连接的，传输时可以复用 SSH 配置，具体写法见SSH 跳板与连接复用的配置说明。

场景	推荐做法	注意点
远端有外网，但安装偶尔失败	先核对放行域名，再重试	用 curl 查连接耗时
远端完全没有外网	本地下载 VSIX，传到远端安装	升级需要手动重复
服务端下载卡住	将 localServerDownload 设为 always	要求本机有 443 出站
自动更新总在转圈	关闭自动更新，改为手动更新	团队内统一版本更稳

更新一直转圈：自动更新开关与代理设置

扩展自动更新由 extensions.autoUpdate 控制，默认开启；extensions.autoCheckUpdates 决定是否检查更新。网络条件不稳的环境里，自动检查更新可能反复触发请求并拖慢界面，可以通过「Disable Auto Update for Extensions」命令关闭，改为在需要的时候手动更新。官方文档还说明，只有已启用的扩展才会自动更新，被禁用的扩展会在重新启用时更新。

如果你的公司网络需要代理，VS Code 使用的是 Chromium 的网络栈，通常会自动读取系统代理设置，同时也提供 http.proxy、http.proxyStrictSSL 和 http.systemCertificates 等设置。遇到证书类错误，优先检查系统证书是否包含公司网关的根证书，而不是把严格校验直接关掉。代理环境变量在终端工具里的写法和排错，可参考代理与超时环境变量的正确写法。

1. 确认本机能否访问扩展市场：在本机装一个小扩展，成功则本地链路正常。
2. 登录远端终端，用 curl 检查上面列出的域名是否可达。
3. 远端不可达就改走 VSIX 离线安装，并把 remote.SSH.localServerDownload 设为 always 处理服务端下载。
4. 仍然卡住，用 Remote.SSH: Show Login Terminal 查看连接过程，再对照Remote-SSH 跨境连接的两个独立故障点排查。

本地链路本身不稳时怎么办

当 localServerDownload 设为 always 之后，所有服务端下载都依赖你本机的出站链路，这时本机到微软下载站点的稳定性就成为关键。如果你发现同一台电脑在不同时段下载速度差异很大，说明瓶颈在出口线路。NasaCode 面向开发场景提供稳定出口和分流规则，可以把 VS Code 相关域名单独走一条线路，其余流量保持直连；这类配置是否带来改善，建议用 curl 的耗时在前后各记录几次来判断。

小结

远程环境里扩展装不上，核心是分清下载发生在本机还是远端：服务端下载可以用 remote.SSH.localServerDownload 调整，扩展安装在远端没有外网时改用 VSIX 离线安装，更新卡住则先关掉自动更新再逐项排查。具体设置名与默认值请以你所用 VS Code 版本的官方文档为准。