第一次在离网 Linux 服务器上搭 VSCode Remote-SSH 时我差点被那句Downloading VS Code Server卡到怀疑人生。SSH 能通、密码能输、远端目录也正常可 VSCode 就是一直提示下载最后等来一个连接失败。后面我把整套离线部署流程跑通又给同事批量装过好几台机器下面这些内容就是完整记录从 Remote-SSH 的下载机制、离线方案选型到分步操作、扩展与依赖处理再到常见报错和批量维护。适合需要在一台无法访问互联网的 Linux 服务器上用 VSCode 远程开发的人尤其是内网测试机、离线研发环境这类场景。先说一句大实话VSCode Remote-SSH 能做的事本质上是把本地的编辑器和远端的服务连接起来但远端并不是只有你的代码文件它还需要一个专门的运行环境。搞清楚这一点后面所有操作就都顺理成章了。1. 先搞明白 Remote-SSH 到底卡在哪一步1.1 vscode-server 不是可有可无的组件Remote-SSH 的架构不像普通的文件同步工具。你在本地打开一个 VSCode 窗口它只是壳远程主机上必须跑一个叫 vscode-server 的服务这个服务负责文件监听、语法分析、扩展宿主、终端会话和调试器。本地客户端和远端服务之间通过既有的 SSH 连接通信不需要额外开放一个监听端口。换句话说SSH 只是管道vscode-server 才是远端真正干活的服务。所以离线环境里你不能只保证 SSH 通。VSCode 客户端在初次连接时会去检查远端用户目录下有没有匹配的 server。没有就尝试从官方下载服务器有就直接启动。这个检查路径是固定的大致是~/.vscode-server/bin/commit-id。commit-id 就是你本地 VSCode 对应的那串版本提交标识。如果你的服务器上已经因为某次失败操作留下了一个坏掉的目录客户端同样可能一直卡住。1.2 默认下载失败是必然的当远端机器无法访问互联网时客户端发起的下载请求要么超时要么被拒。你会在 Remote-SSH 的输出日志里看到这一类信息[error] Downloading VS Code Server failed. Please try again later. [error] Failed to download VS Code Server. [error] Error: connect ETIMEDOUT 20.xxx.xxx.xxx:443这个阶段很多人会去折腾网络配置其实方向错了。既然客户端检查的是某个固定目录下的固定文件那我们完全可以绕过自动下载手动把 server 包放到它该在的位置。后面所有步骤都是在做这件事。注意Remote-SSH 能通的另一个前提是你的电脑和目标服务器之间本来就要有一条可用的 SSH 链路。离线环境只影响目标服务器访问互联网不影响局域网内两台机器互访。如果 SSH 本身都不通Remote-SSH 无论如何也起不来。2. 离线方案的整体思路和取舍2.1 核心思路把 server 包当成普通安装包去搬运手动部署的思路不复杂在任意一台能上网的电脑上下载与本地 VSCode 完全同版本、同平台的 vscode-server 压缩包。把这个包通过 U 盘、scp、rsync 等任意方式传到目标机。在目标机上解压到~/.vscode-server/bin/commit-id目录。回到 VSCode 重新连接客户端发现 server 已经存在就不会再触发下载。这个方案能成立的关键是 VSCode 客户端判断“远端服务是否就绪”时只看固定路径和 commit-id。只要这两个条件满足它就不会再去请求官方下载站点。所以离线部署不是要改 Remote-SSH 的代码而是把自动下载变成手动投递。2.2 为什么不直接用浏览器版方案有人会推荐在服务器上装一个浏览器访问的 code-server把它当 VSCode 用。这套方案也可以离线跑但它和你熟悉的桌面版 VSCode 并不是完全一样的体验多窗口管理、部分快捷键、调试器 UI、某些只认 Remote 类型的扩展在浏览器里表现有差异。如果你团队已经习惯了 Remote-SSH 的工作流做离线部署时尽量保持原生 Remote-SSH 方案后面恢复联网也不用切来切去。Remote-SSH 方案还有一个好处一旦把 vscode-server 放好后续你做的本地调试、端口转发、终端复用都和在线环境一样没有额外学习成本。server 压缩包一般几十兆到一百兆按版本归档后一次性投入长期受益。3. 离线部署实操按步骤抄就行3.1 锁定本地 VSCode 的 commit id第一步是拿到你本地 VSCode 的完整版本号和 commit id。最直接的方式是在本机命令行执行code --version输出会包含三行大概长这样1.86.2 e180c05f7f13 x64第二行e180c05f7f13就是 commit id。如果你电脑上code命令不在 PATH 里也可以打开 VSCode 的Help - About对话框界面里同样有这条信息。这里有个容易忽略的点Remote-SSH server 的版本与本地客户端是强绑定的理论上一个本地 VSCode 版本对应一个 commit id。如果团队里有人用 1.86.2有人用 1.87.1那么同一台远端服务器上~/.vscode-server/bin下就要同时放两个不同 commit-id 的目录。所以第一批部署时最好先把所有人的本地 VSCode 锁在同一版本不然每多一个版本就要多搬一次。3.2 在联网电脑上下载 server 包拿到 commit id 后去任意一台能上网的电脑上下载对应的 Linux server 压缩包。官方下载地址的规则是curl -L https://update.code.visualstudio.com/commit:e180c05f7f13/server-linux-x64/stable -o vscode-server.tar.gzserver-linux-x64里的“x64”要根据目标机架构替换目标机架构URL 中的路径片段Linux x64server-linux-x64Linux ARM64server-linux-arm64Linux ARM 32 位server-linux-armhf下载完成后最好看一眼文件大小。正常应该在几十兆到一百多兆之间如果只有几 KB大概率是 URL 拼错了用文本编辑器打开那个文件里面往往是一段错误提示。如果联网电脑和离线服务器之间的网络路径也不通就用 U 盘这类介质传递。只要最终能把 tar.gz 放到服务器上就行过程不限。3.3 把包传到目标机假设服务器地址和用户是user10.0.0.5最简单的传法是 scpscp -P 22 vscode-server.tar.gz user10.0.0.5:/tmp/如果端口不是 22就把-P 22换成实际端口。大文件用 rsync 更稳中途断了还能断点续传rsync -avP vscode-server.tar.gz user10.0.0.5:/tmp/传完后我会顺手在服务器上确认一下 md5 或者文件大小防止传到一半损坏。服务器上直接执行ll /tmp/vscode-server.tar.gz看到大小和本机一致再进行下一步。3.4 在目标机解压到正确位置登录服务器用登录用户自己的身份操作不要一上来就 sudo。关键命令如下ssh user10.0.0.5 mkdir -p ~/.vscode-server/bin/e180c05f7f13 tar -xzf /tmp/vscode-server.tar.gz -C ~/.vscode-server/bin/e180c05f7f13 --strip-components1这里的--strip-components1非常关键。如果你少了这个参数解压后会在bin/e180c05f7f13下多出一层vscode-server-linux-x64子目录VSCode 客户端按固定路径找server.sh时找不到还是会重新触发下载。解压完成后检查一下目录结构ls ~/.vscode-server/bin/e180c05f7f13正常情况下应该能看到bin、node、out、package.json、server.sh这些内容。如果在bin/e180c05f7f13下看到vscode-server-linux-x64这个文件夹说明你没加--strip-components1重新解压一遍就好。还有一个容易踩的坑如果这个压缩包是在 Windows 上解压过再重新打包的Linux 上的可执行权限可能会丢。遇到启动失败先跑一下chmod x ~/.vscode-server/bin/e180c05f7f13/server.sh3.5 重新连接并确认回到本地 VSCode在 Remote Explorer 里重新连接目标主机。如果一切正常状态栏不会出现Downloading VS Code Server而是直接进入远程窗口。这时你随便打开一个文件看看右下角是否出现“Remote”连接提示基本就说明 server 已经跑起来了。如果刚才连到一半失败服务器上可能残留一个半死不活的进程。不要直接重试先在 VSCode 命令面板里执行Remote-SSH: Kill VS Code Server on Host然后再重连。这样能确保下一次启动是干净状态。4. 离线环境下的扩展与语言服务4.1 远程扩展才是真正跑在 server 上的那一半VSCode 扩展里有一部分是界面增强类运行在本地另一部分是语言服务、调试器、格式化工具在远程模式下是运行在服务器上的。比如 Python 扩展的语言服务器在远程窗口里启动时实际上是 vscode-server 在跑它。这个区别在离线环境里特别重要你在本地把扩展装得再全远程窗口里该装的那份也不会自动出现。所以离线环境要提前准备两部分一是 vscode-server 本身二是远程扩展的安装包。两者都要像搬安装包一样提前搬到目标机。4.2 用 .vsix 离线装扩展扩展市场里每个扩展都有对应的.vsix安装包。在一台能上网的电脑上打开扩展市场网页搜索你需要的扩展进入详情页后一般能直接下载.vsix文件。拿到文件后传到目标机scp python.vsix user10.0.0.5:/tmp/然后有两种安装方式。第一种是在 Remote-SSH 远程窗口里执行命令面板的Extensions: Install from VSIX选择本地或远端路径VSCode 会把它安装到远端扩展目录。第二种是直接在目标机上用 vscode-server 自带的命令行工具装~/.vscode-server/bin/e180c05f7f13/bin/code-server --install-extension /tmp/python.vsix这两种方式的效果一样都是把扩展放到远端服务器的~/.vscode-server/extensions下。我更喜欢第二种因为不依赖 VSCode 图形界面适合批量操作。4.3 离线依赖才是后半天时间扩展装好之后真正写代码还需要解释器和第三方库。Python 项目如果机器没有外网pip 装包会失败所以要在联网机器上把 wheel 包提前下载好。一个通用姿势是用 pip downloadpip download -r requirements.txt -d wheels \ --platform manylinux_2_17_x86_64 \ --only-binary:all: \ --python-version 3.11把--platform和--python-version换成目标机的实际架构和 Python 版本然后整个wheels目录拷到目标机在目标机上执行pip install --no-index --find-links/tmp/wheels -r requirements.txtNode 项目如果node_modules实在没法通过内网源装一个笨但有效的办法是在同架构的联网机器上把依赖装好再把整个目录拷过去。条件允许的话尽量用.deb、.whl、.tar.xz这类官方安装包离线安装比直接拷安装目录更不容易出问题。5. 常见问题与排查5.1 一直卡在 Downloading绝大多数情况是目录没放对或者 commit id 写错。先打开 Remote-SSH 的输出日志看它到底想下载哪个 commit-id然后去服务器上核对ls ~/.vscode-server/bin/如果列表里没有日志里那个 commit-id说明版本对不上。如果有目录再看目录下有没有server.sh没有就说明多了一层目录结构。5.2 SSH 能通VSCode 就是连不上Remote-SSH 本质上就是个 SSH 客户端所以先用命令行单独测一遍ssh user10.0.0.5如果命令行 SSH 都不通问题在账号、密钥、端口或跳板机配置和离线 server 无关。如果命令行能进VSCode 还是失败重点看 Remote-SSH 日志里的 server 启动过程确认 server 进程有没有被系统杀掉以及报错信息里提到的文件路径。5.3 报 node 相关 so 文件找不到目标系统太旧时新版 vscode-server 的 node 会报类似GLIBC_2.xx not found的错误。这种情况一般是因为系统基础库版本不够。经验解法是换一个旧版本的 VSCode 客户端因为老版本对应老 server对系统底包的要求会低一些或者把开发环境放到一个满足要求的容器或虚拟环境里跑。5.4 权限问题导致连接失败如果~/.vscode-server是用 root 建的普通用户连接时经常出现Permission denied。解决方法是删除或 chown让登录用户拥有这个目录sudo chown -R user:user ~/.vscode-server之后的 mkdir、解压、安装扩展都用登录用户身份操作不要习惯性加 sudo否则很容易留下一堆 root 属主的文件。把上面这些整理成一张速查表用的时候直接对照现象大概率原因处理方向一直 Downloading VS Code Serverserver 目录不存在或路径多一层核对日志里的 commit-id 和server.sh位置连接后立刻退出server 权限丢失或系统库过旧重新 chmod或换旧版 VSCodePermission denied目录属主不是登录用户chown 到对应用户某天突然连不上本地 VSCode 自动升级了版本按新 commit-id 重新部署并归档旧包6. 批量部署与团队维护心得6.1 把部署脚本固化下来手敲命令容易出错整理成一个脚本后批量部署只是执行一遍的事。下面这个脚本是我日常用的简化版#!/usr/bin/env bash set -euo pipefail TARGET$1 # userhost COMMIT_IDe180c05f7f13 ARCHx64 TARBALL/tmp/vscode-server-linux-${ARCH}.tar.gz ssh $TARGET mkdir -p ~/.vscode-server/bin/${COMMIT_ID} scp $TARBALL $TARGET:/tmp/ ssh $TARGET tar -xzf /tmp/vscode-server-linux-${ARCH}.tar.gz \ -C ~/.vscode-server/bin/${COMMIT_ID} --strip-components1 \ ls ~/.vscode-server/bin/${COMMIT_ID}/server.sh脚本里把COMMIT_ID、ARCH、TARBALL显式定义出来后面换版本时只改这三行。如果服务器 SSH 端口不是 22记得在ssh和scp命令里加上-p参数。6.2 建立版本缓存库我建议在团队内部维护一个共享归档目录按 VSCode 版本号分类vscode-server-offline/ 1.86.2/ server-linux-x64.tar.gz server-linux-arm64.tar.gz python.vsix go.vsix每次有人升级本地 VSCode就在归档目录里补一个新 server 包。以后给新机器配环境直接从共享目录拷贝不用再让每个人去外网找下载链接。这个方法特别适合多台离线机器的批量交付。6.3 让团队少踩坑的关键踩过几次坑之后我最深的体会是离线 Remote-SSH 的本质不是网络问题而是版本管理问题。只要 commit-id 对上、目录结构放对server 包搬过去就能跑。所以我给团队定了一条规则本地 VSCode 大版本升级前先通知管理归档的人server 包同步更新后再升级。这样做的效果很明显自从统一管理之后离线机器上再也没出现过“连不上还得现场救火”的情况。如果你正准备给一批离网机器配环境先用一台机器把流程完整跑一遍再决定是手动操作还是写脚本。等脚本和归档目录固定下来后面的每一台新机器都会变得非常省事。