内网/无网环境必备：VS Code Remote-SSH 离线包下载与手动部署教程

适用场景：公司内网、涉密环境、远程服务器无法联网、网络代理不稳定……

TL;DR：赶时间的熟手，请直接拉到文末查看「五、一键速查表」。

只要你的远程主机连不上外网，这篇教程就能救你。全文以 VS Code 1.138.0 + Remote-SSH 0.129.2026090915 为例，方法适用于任意版本及主流操作系统。

一、为什么要费劲搞这套离线包？

1.1 先搞懂 Remote-SSH 的工作原理

很多人以为 Remote-SSH 扩展装好就能连远程了，其实它是两个进程在配合：

sequenceDiagram
    participant Local as 本地电脑 (Win/macOS)
    participant SSH as SSH 加密通道
    participant Remote as 远程服务器 (Linux)
    
    Local->>SSH: VS Code 客户端 (Remote-SSH 扩展)
    SSH->>Remote: 建立连接
    Note over Remote: VS Code Server 服务端<br/>(代码补全/终端/调试都在这里跑)

关键点：你编辑代码时的所有重活（语言补全、调试、终端、扩展运行）都不在本地，而是在远程的 vscode-server 上跑。本地那半个只是个「壳」。

1.2 为什么远程主机断网 = 连接失败

正常情况下，你第一次点「连接到 SSH 主机」时，Remote-SSH 会自动通过远程主机去外网下载对应版本的 vscode-server。流程很顺滑，但它有一个致命前提：

远程主机必须能访问 update.code.visualstudio.com。

远程服务器在内网、被防火墙挡住、或者压根没有外网出口时，你就会看到经典的卡死画面：

Setting up SSH Host: Downloading VS Code Server
……（卡在这里 forever）

1.3 还有两个隐藏的坑

1. 版本必须严格匹配：本地 VS Code 是 1.138.0，远程 server 也必须是 1.138.0（准确说是同一个 commit）。版本对不上，客户端会无视你手动部署的 server，重新联网下载——又卡死。
2. Remote-SSH 扩展本身也可能装不了：有些内网环境 VS Code 也没法联网装扩展，需要 VSIX 离线安装。

所以，一个完整的「离线 Remote-SSH 环境」需要四件套：

⚠️ 另外版本选择上有个讲究：先确定你要下载的 VS Code 版本，再下载配套的 server，最后装扩展。顺序反了容易对不上 commit。

二、怎么获取（手把手下载篇）

2.1 第一步：查最新稳定版版本号

浏览器打开官方 Release API（直接返回 JSON）：

https://update.code.visualstudio.com/api/releases/stable

返回列表的第一个就是最新版本，例如 ["1.138.0", "1.137.1", ...]。

2.2 第二步：拿到这个版本的 commit hash

server 的下载链接是按 commit hash（而不是版本号）索引的，获取方式有两种：

捷径（推荐）：如果你本地已经安装好了 VS Code，直接在菜单栏点击「帮助」 -> 「关于」（macOS 下是 Code -> 关于 VS Code），复制里面的 提交 (Commit) 哈希值即可，无需再去查 API。

API 查询法：浏览器或命令行访问以下链接：

https://update.code.visualstudio.com/api/update/win32-x64-user/stable/latest

(注：此处 API 虽带有 win32，但同一版本的 commit hash 跨平台是一致的)

返回 JSON 里就有 commit（示例）：

{
  "version": "7debcd0e2acdea1c52de81bf9ee1620444407dda",
  "url": "https://vscode.download.prss.microsoft.com/dbazure/download/stable/7debcd0e.../VSCodeUserSetup-x64-1.138.0.exe"
}

💡 这里的 version 字段填的就是 commit hash。

2.3 第三步：下载四个文件

① 客户端安装程序

直接套用模板下载你需要的版本：

• Windows (User Setup): [https://update.code.visualstudio.com/latest/win32-x64-user/stable](https://update.code.visualstudio.com/latest/win32-x64-user/stable)
• macOS (Apple Silicon): [https://update.code.visualstudio.com/latest/darwin-arm64/stable](https://update.code.visualstudio.com/latest/darwin-arm64/stable)
• macOS (Intel): [https://update.code.visualstudio.com/latest/darwin/stable](https://update.code.visualstudio.com/latest/darwin/stable)

② Remote-SSH 扩展（vsix）

下载链接模板：

https://marketplace.visualstudio.com/_apis/public/gallery/publishers/ms-vscode-remote/vsextensions/remote-ssh/{版本号}/vspackage

⚠️ 大坑预警：这个接口返回的是 gzip 压缩过的数据，直接保存下来不是标准的 zip，无法直接安装！推荐使用 curl 时加上 --compressed 参数，它会自动处理 gzip 流并保存为正常的扩展包，一行命令搞定：

curl -s --compressed -X POST "https://marketplace.visualstudio.com/_apis/public/gallery/publishers/ms-vscode-remote/vsextensions/remote-ssh/0.129.2026090915/vspackage" -o remote-ssh.vsix

③ vscode-server 服务端（tar.gz）

套用这个模板（把 commit 换成第 2.2 步拿到的 hash）：

https://update.code.visualstudio.com/commit:{commit}/server-linux-x64/stable
https://update.code.visualstudio.com/commit:{commit}/server-linux-arm64/stable

实际例子（1.138.0）：

https://update.code.visualstudio.com/commit:7debcd0e2acdea1c52de81bf9ee1620444407dda/server-linux-x64/stable

• x64：普通云主机、公司服务器（绝大多数情况）
• arm64：树莓派、Oracle Cloud (甲骨文云) 免费 ARM 实例、ARM 架构的国产化服务器（如鲲鹏）

💡 远程主机是什么架构不确定？连上去执行 uname -m：输出 x86_64 选 x64，aarch64 选 arm64。

三、怎么用（手把手部署篇）

3.1 本地端：装 VS Code + 离线装 Remote-SSH 扩展

1. 安装下载好的 VS Code 本体。
2. 离线安装扩展：打开扩展面板（Ctrl+Shift+X 或 Cmd+Shift+X）→ 右上角 ··· 菜单 → 「从 VSIX 安装…」 → 选中下载好的 remote-ssh.vsix 文件。
3. 重启 VS Code，左侧出现远程资源管理器图标（屏幕形状）即安装成功。

3.2 远程端：手动部署 vscode-server（联网机器可跳过）

第 1 步：确认目标目录名

目录名必须是 commit hash（2.2 步查到的那串字符），绝不是版本号！

第 2 步：上传并解压到指定位置

把 tar.gz 传到远程主机（scp / sftp / U 盘 / 内网 ftp 都行），然后在远程终端执行：

# 1. 创建目标目录（把 commit 换成你的 hash）
COMMIT=7debcd0e2acdea1c52de81bf9ee1620444407dda
mkdir -p ~/.vscode-server/bin/$COMMIT

# 2. 解压到目标目录
tar -xzf vscode-server-linux-x64-1.138.0.tar.gz \
    -C ~/.vscode-server/bin/$COMMIT --strip-components=1

# 3. 验证：关键文件存在即部署正确
ls ~/.vscode-server/bin/$COMMIT/bin/code-server- 2>/dev/null || \
ls ~/.vscode-server/bin/$COMMIT

🛑 最容易翻车的地方：千万别漏了 --strip-components=1 参数！如果不加这个参数，解出来会变成 ~/.vscode-server/bin/$COMMIT/vscode-server-linux-x64/...，多套了一层目录，客户端绝对识别不到，依然会尝试联网下载导致卡死。

正确的目录结构长这样：

~/.vscode-server/
└── bin/
    └── 7debcd0e2acdea1c52de81bf9ee1620444407dda/   ← 目录名 = commit
        ├── bin/
        ├── node
        ├── out/
        ├── package.json
        └── ...

3.3 连接！

1. F1（或 Ctrl+Shift+P / Cmd+Shift+P）→ 输入 Remote-SSH: Connect to Host…
2. 输入 用户名@主机IP，回车，选平台（Linux），输入密码或等密钥认证通过。
3. 状态栏左下角出现 SSH: 主机名，绿了就是成功 🎉
4. 文件 → 打开文件夹，选中远程的代码目录，开始干活。

3.4 首次连接卡住的排查清单

四、FAQ / 踩坑实录

Q1：VS Code 升级了，远程要重新搞一遍吗？

要。客户端升级后 commit 变了，旧 server 会被判定不匹配。提前把新版 server 的 tar.gz 一起下好，升级当天直接换目录。

Q2：远程服务器磁盘越用越少怎么办？

VS Code 有个通病，每次升级客户端，旧版本的 server 还会残留在 ~/.vscode-server/bin/ 目录下。如果你的远程机器（特别是云服务器的免费小鸡）空间紧张，记得定期去这个目录下删掉旧的 commit 文件夹。

Q3：User Setup 和 System Setup 怎么选（Windows）？

没有管理员权限、或只想给当前用户装 → User Setup；多人共用电脑 / 要装到 Program Files → System Setup。两者功能完全一样。

Q4：远程主机是 Windows 怎么办？

Remote-SSH 也支持 Windows 服务端（需装 OpenSSH Server），对应的服务端包是 server-win32-x64，套路完全一样。

五、一键速查表

① 查版本号:   https://update.code.visualstudio.com/api/releases/stable
② 查 commit: 本地 VS Code -> 帮助/Code -> 关于
③ 客户端exe: https://update.code.visualstudio.com/latest/win32-x64-user/stable (Win)
             https://update.code.visualstudio.com/latest/darwin-arm64/stable (Mac M系列)
④ 扩展vsix:  curl -s --compressed -X POST "https://marketplace.visualstudio.com/_apis/public/gallery/publishers/ms-vscode-remote/vsextensions/remote-ssh/{版本号}/vspackage" -o remote-ssh.vsix
⑤ 服务端包:  https://update.code.visualstudio.com/commit:{commit}/server-linux-x64/stable
⑥ 部署位置:  远程 ~/.vscode-server/bin/{commit}/  （解压切记 --strip-components=1）