从 VS Code 1.99 开始，Remote - SSH 下载的新版 VS Code Server 要求 glibc 2.28 或更高版本。CentOS 7.9 自带的 glibc 长期停留在 2.17，因此会出现“普通 SSH 可以登录，但 VS Code 无法完成远程连接”的情况。

本文使用开源项目 hsfzxjy/vscode-remote-glibc-patch 提供的预编译 sysroot，为 VS Code Server 单独准备 glibc 2.28、动态链接器和 patchelf。整个过程不会替换 CentOS 的系统 glibc，已经在一台 CentOS 7.9 x86_64 服务器上验证可用。

**先说明支持边界：**VS Code 官方将这种 sysroot + patchelf 方法定义为技术性过渡方案，并不属于正式支持的运行场景。它适合为旧系统争取迁移时间，长期方案仍然是升级到 RHEL 8、Rocky Linux 8/9、AlmaLinux 8/9、Ubuntu 20.04+ 等受支持系统。

一、问题是怎么出现的

CentOS 7.9 的系统运行库版本通常如下：

cat /etc/centos-release
getconf GNU_LIBC_VERSION
ldd --version | head -n 1

典型输出：

CentOS Linux release 7.9.2009 (Core)
glibc 2.17
ldd (GNU libc) 2.17

而 VS Code 官方文档说明，从 VS Code 1.99（2025 年 3 月）开始，预编译 VS Code Server 基于 glibc 2.28 或更新版本。官方列出的基础要求还包括 kernel 4.18、libstdc++ 3.4.25 和 binutils 2.29。

检查项	CentOS 7.9 常见版本	新版 VS Code Server 基础要求
glibc	2.17	2.28 或更高
Linux kernel	3.10.x	官方基线为 4.18 或更高
libstdc++	通常低于新基线	GLIBCXX 3.4.25 或更高
处理方式	不升级系统库	给 VS Code Server 提供私有 sysroot

因此，这类故障的本质通常不是 SSH 密码、密钥或端口问题，而是远端下载下来的 VS Code Server 二进制无法在旧运行库环境中启动。

常见表现

终端执行 ssh <服务器> 可以正常登录。
VS Code Remote - SSH 一直停留在 Installing VS Code Server、Waiting for server log 或反复重连。
Remote - SSH 日志中出现 GLIBC_2.28、GLIBCXX、server requirements 或 prerequisite check 相关错误。
旧版本 VS Code 曾经可以连接，升级客户端后开始失败。

二、解决思路：不要升级系统 glibc

直接替换 CentOS 7 的 /lib64/libc.so.6 风险极高。glibc 是系统中大量基础命令、服务和软件共同依赖的核心组件，一旦替换失败，可能造成 SSH、yum、systemd 或其他服务无法启动。

**本文采用隔离方案：**系统继续使用 glibc 2.17，仅在 VS Code Server 安装和启动时，用 patchelf 将它自带 Node 二进制的 interpreter 和 rpath 指向一套独立的 glibc 2.28 sysroot。

项目中的 init.sh 会输出下面三个环境变量：

环境变量	用途
`VSCODE_SERVER_CUSTOM_GLIBC_LINKER`	指定私有 sysroot 中的动态链接器，供 patchelf 设置 ELF interpreter。
`VSCODE_SERVER_CUSTOM_GLIBC_PATH`	指定私有运行库搜索路径，供 patchelf 设置 rpath。
`VSCODE_SERVER_PATCHELF_PATH`	指定远端 patchelf 可执行文件。

连接链路可以概括为：

Remote - SSH 登录服务器并加载用户 Shell 配置。
VS Code Server 安装程序读取三个 VSCODE_SERVER_* 环境变量。
安装程序调用 patchelf 修改 Server 内置 Node 的 interpreter 和 rpath。
VS Code Server 使用私有 glibc 2.28 启动；其他系统程序继续使用 glibc 2.17。

三、开始前的检查

1. 确认系统架构

uname -m

本文使用的 Release 包适用于 x86_64。如果输出为 aarch64、armv7l 或其他架构，不要直接使用本文的 x86_64 包。

2. 查看系统、内核和 glibc

cat /etc/centos-release
uname -r
getconf GNU_LIBC_VERSION

本文实测环境为 CentOS Linux 7.9.2009、x86_64、3.10 系列内核和 glibc 2.17。

3. 根据内核选择 Release 包

项目当前提供四个 x86_64 构建包。文件名中的 kernel 版本是该 sysroot 的最低兼容内核基线，应选择“小于或等于服务器实际内核”的版本。

最低内核基线	Release 文件名
3.4.113	`x86_64-kernel-3.4.113-gcc-8.5.0-glibc-2.28.tgz`
4.1.49	`x86_64-kernel-4.1.49-gcc-8.5.0-glibc-2.28.tgz`
4.14.329	`x86_64-kernel-4.14.329-gcc-8.5.0-glibc-2.28.tgz`
5.10.233	`x86_64-kernel-5.10.233-gcc-8.5.0-glibc-2.28.tgz`

CentOS 7.9 常见内核为 3.10.x。因为 3.4.113 ≤ 3.10.x，而 4.1.49 > 3.10.x，所以应选择 kernel-3.4.113 包。不要误以为文件名版本越新越好。

四、完整安装步骤

以下命令默认以 root 用户执行，将私有运行库安装到 /root/glibc-patch。普通用户也可以把目录改为 $HOME/glibc-patch。

步骤 1：下载预编译包

cd /root
curl -fL --retry 3 \
  -o x86_64-kernel-3.4.113-gcc-8.5.0-glibc-2.28.tgz \
  https://github.com/hsfzxjy/vscode-remote-glibc-patch/releases/download/BUILD/x86_64-kernel-3.4.113-gcc-8.5.0-glibc-2.28.tgz

如果服务器不能直接访问 GitHub，可以在本地浏览器下载后，通过 scp、SFTP 或堡垒机上传到服务器。

步骤 2：记录文件哈希

sha256sum /root/x86_64-kernel-3.4.113-gcc-8.5.0-glibc-2.28.tgz

该命令主要用于记录和比较传输前后的文件是否一致。第三方预编译二进制仍然存在供应链风险；安全要求较高的环境应审查项目工作流并自行构建。

步骤 3：解压到独立目录

mkdir -p /root/glibc-patch
tar -xzf /root/x86_64-kernel-3.4.113-gcc-8.5.0-glibc-2.28.tgz \
  -C /root/glibc-patch

chmod +x /root/glibc-patch/init.sh
chmod +x /root/glibc-patch/patchelf

检查关键文件：

test -x /root/glibc-patch/init.sh && echo "init.sh OK"
test -x /root/glibc-patch/patchelf && echo "patchelf OK"
find /root/glibc-patch -path '*/sysroot/lib/ld-linux-x86-64.so.2' -print

项目 Release 包约 117 MB，解压后的工具链和 sysroot 占用约 480 MB，实际大小可能随 Release 更新变化。

步骤 4：先查看 init.sh 将设置什么

/root/glibc-patch/init.sh

应输出三个 export VSCODE_SERVER_... 语句。这里的脚本不会直接修改系统，只负责根据解压目录计算私有动态链接器、运行库路径和 patchelf 路径。

步骤 5：写入 Shell 配置

将下面一行加入远程用户的 ~/.bashrc：

grep -qxF 'eval "$(/root/glibc-patch/init.sh)"' ~/.bashrc || \
  echo 'eval "$(/root/glibc-patch/init.sh)"' >> ~/.bashrc

同时确认 ~/.bash_profile 会加载 ~/.bashrc。CentOS 默认一般已有下面这段：

if [ -f ~/.bashrc ]; then
    . ~/.bashrc
fi

如果没有，可以追加：

grep -q '\. ~/.bashrc' ~/.bash_profile || cat >> ~/.bash_profile <<'EOF'

if [ -f ~/.bashrc ]; then
    . ~/.bashrc
fi
EOF

Remote - SSH 在不同版本和配置下可能使用登录 Shell、非登录 Shell或命令模式。只修改 ~/.bashrc 但登录链路没有加载它，是“手工 source 后正常、VS Code 仍失败”的常见原因。

步骤 6：加载并验证环境变量

source ~/.bashrc
env | grep '^VSCODE_SERVER_' | sort

应看到：

VSCODE_SERVER_CUSTOM_GLIBC_LINKER=.../sysroot/lib/ld-linux-x86-64.so.2
VSCODE_SERVER_CUSTOM_GLIBC_PATH=...
VSCODE_SERVER_PATCHELF_PATH=/root/glibc-patch/patchelf

进一步检查所有路径：

test -x "$VSCODE_SERVER_CUSTOM_GLIBC_LINKER" && echo "linker OK"
test -x "$VSCODE_SERVER_PATCHELF_PATH" && echo "patchelf OK"
"$VSCODE_SERVER_PATCHELF_PATH" --version

项目 Release 使用 patchelf 0.18.0。VS Code 官方特别提醒，patchelf 0.17.x 可能导致远程 Server 段错误，建议使用 0.18.x 或更高版本。

步骤 7：验证重新登录后仍然有效

退出当前 SSH 会话后重新登录，或从本地执行：

ssh <用户>@<服务器 IP> \
  'bash -lc "env | grep ^VSCODE_SERVER_ | sort"'

如果重新登录后没有任何输出，说明 VS Code 建立连接时大概率也读不到这些变量，应优先排查 ~/.bash_profile、~/.bashrc 和远端默认 Shell。

步骤 8：让 VS Code 重新建立连接

关闭所有连接到该主机的 VS Code 窗口。
在命令面板执行 Remote-SSH: Kill VS Code Server on Host...，选择目标服务器。
重新执行 Remote-SSH: Connect to Host...。
第一次连接需要重新下载和修补 VS Code Server，等待时间会比普通重连长。

如果之前的失败安装留下了损坏目录，可以先备份而不是直接删除：

mv ~/.vscode-server ~/.vscode-server.bak.$(date +%Y%m%d-%H%M%S)

然后重新连接。确认新连接正常后，再择机清理备份目录。

五、如何确认补丁真正生效

只看到 VS Code 窗口打开还不够。建议从环境变量、安装日志和 ELF interpreter 三个层次进行验证。

验证 1：检查系统 glibc 没有被修改

getconf GNU_LIBC_VERSION

预期仍然是：

glibc 2.17

这是正常且符合预期的结果。本文不是将整个 CentOS 7 升级到 glibc 2.28。

验证 2：检查 VS Code Server 日志

grep -R -E 'Patching glibc|Patching linker|Patching complete' \
  ~/.vscode-server/cli/servers/*/log.txt 2>/dev/null

成功日志通常包含：

Patching glibc from ... with .../patchelf...
Patching linker from .../ld-linux-x86-64.so.2 with .../patchelf...
Patching complete.

在本文参考服务器上，这三行已经实际出现，随后日志显示 Visual Studio Code Server 成功启动并监听本地 Unix Socket。

验证 3：检查 VS Code Server 内置 Node 的 interpreter

NODE_BIN=$(find ~/.vscode-server/cli/servers \
  -path '*/server/node' -type f 2>/dev/null | sort | tail -n 1)

echo "$NODE_BIN"
readelf -l "$NODE_BIN" | grep 'Requesting program interpreter'
"$NODE_BIN" --version

interpreter 应指向私有目录，例如：

[Requesting program interpreter: /root/glibc-patch/.../sysroot/lib/ld-linux-x86-64.so.2]

参考服务器的 Server Node 已被设置为上述私有动态链接器，这比单纯检查环境变量更能证明 patchelf 操作已经完成。

验证 4：确认 VS Code 功能正常

远程文件树能够展开。
集成终端能够创建并执行命令。
远程扩展宿主可以启动。
安装在 Remote 侧的语言扩展能够正常加载。
重新打开窗口或断线重连后仍能恢复。

六、这个项目做了什么

vscode-remote-glibc-patch 的价值不是发明了另一套补丁机制，而是把 VS Code 官方建议的 sysroot + patchelf 方案预先构建并打包，省去了在旧服务器上编译完整工具链的时间。

1. 使用 crosstool-ng 构建 sysroot

项目的 GitHub Actions 工作流使用 crosstool-ng 1.26.0，以 GCC 8.5.0 和 glibc 2.28 配置生成 x86_64 工具链。构建矩阵分别设置 3.4.113、4.1.49、4.14.329 和 5.10.233 作为最低内核版本。

2. 根据目标内核调整配置

configs/patch_linux.py 会根据构建矩阵修改 crosstool-ng 配置中的 Linux 版本选择和 CT_GLIBC_MIN_KERNEL，因此不同 Release 包不能随意混用。

3. 打包 patchelf 0.18.0

构建工作流从 NixOS/patchelf Release 获取 0.18.0，并与 sysroot、init.sh 一起打包。

4. init.sh 只输出环境变量

项目的 init.sh 根据自身所在目录定位 sysroot，然后输出三个 export 语句。Shell 配置中的：

eval "$(/root/glibc-patch/init.sh)"

会执行这些 export 语句，把变量放入当前 Shell 环境。脚本不复制系统库、不覆盖 /lib64，也不修改系统动态链接器。

七、常见问题与排查

问题 1：环境变量在当前终端存在，VS Code 仍然看不到

**原因：**VS Code 建立 SSH 会话时没有加载你修改的配置文件。

检查：

getent passwd "$(whoami)" | cut -d: -f7
bash -lc 'env | grep ^VSCODE_SERVER_ | sort'
grep -n 'glibc-patch' ~/.bashrc ~/.bash_profile 2>/dev/null

**处理：**确保远端用户使用 Bash，并确保 ~/.bash_profile 加载 ~/.bashrc。如果使用 zsh 或其他 Shell，应写入对应 profile。

问题 2：选错 kernel 构建包

**原则：**包名中的最低内核版本必须小于或等于实际内核。3.10 内核选择 3.4.113 包；不能选择最低要求为 4.1.49、4.14.329 或 5.10.233 的包。

问题 3：patchelf 报错或 Server 段错误

/root/glibc-patch/patchelf --version
file /root/glibc-patch/patchelf
uname -m

确认 patchelf 为 x86_64、可执行且版本至少为 0.18.x。不要换用已知可能导致 Server 段错误的 0.17.x。

问题 4：日志没有出现 Patching complete

依次检查：

三个环境变量是否在重新登录后仍存在。
linker、sysroot 目录和 patchelf 是否存在且可执行。
压缩包是否完整，架构和内核基线是否正确。
是否仍在复用之前失败或损坏的 VS Code Server 安装。
打开 VS Code 的“Remote - SSH”输出面板，查看第一处真实错误，而不是最后一条重试信息。

问题 5：连接成功，但某些远程扩展仍然失败

补丁主要解决 VS Code Server 自身的运行库兼容问题。第三方扩展可能带有自己的原生二进制、Node Addon 或系统依赖，并不一定自动使用同一套私有 sysroot。应根据扩展日志单独检查其 glibc、libstdc++、Python、Java 或其他依赖。

问题 6：如何查看最原始的 Remote - SSH 日志

在 VS Code 打开“查看 → 输出”。
右上角通道选择“Remote - SSH”。
从第一次出现 glibc、GLIBCXX、requirements 或 server start failure 的位置开始阅读。

八、升级与回滚

回滚配置

删除 ~/.bashrc 中的这一行：

eval "$(/root/glibc-patch/init.sh)"

退出并重新登录，然后确认变量已经消失：

env | grep '^VSCODE_SERVER_' || echo "custom VS Code glibc variables removed"

确认不再需要后，可以删除私有目录和归档：

rm -rf /root/glibc-patch
rm -f /root/x86_64-kernel-3.4.113-gcc-8.5.0-glibc-2.28.tgz

执行删除前必须再次确认路径。不要删除 /lib64、/usr/lib64 或任何系统 glibc 文件。本文方案的可回滚性，正是来自所有新增文件都位于独立目录。

VS Code 升级后再次失败怎么办

VS Code、内置 Node 和 Remote - SSH 的要求仍可能继续变化。升级客户端后如果问题复现，应先查看最新官方 FAQ 和项目 Release/Issue，不要默认旧 sysroot 永久兼容。必要时升级私有 sysroot、重新安装 VS Code Server，或者迁移操作系统。

九、安全与生产建议

**不要升级或覆盖系统 glibc：**这是最重要的风险边界。
**不要全局设置 LD_LIBRARY_PATH：**避免让系统服务和普通命令误用私有运行库。
**按用户配置优先：**除非确实要让所有用户使用，否则不要直接修改 /etc/profile 或 /etc/bashrc。
**审查第三方二进制：**高安全环境建议复核 GitHub Actions 构建流程并自行构建、签名和分发。
**保留迁移计划：**CentOS 7 已结束生命周期，私有 glibc 只能解决部分开发工具兼容问题，不能恢复操作系统的安全支持。

十、结语

解决 CentOS 7.9 上新版 VS Code Remote - SSH 的 glibc 兼容问题，关键不是“把系统 glibc 强行升级到 2.28”，而是把影响范围限制在 VS Code Server：

根据实际内核选择正确的预编译 sysroot。
通过三个 VS Code 专用环境变量提供 linker、library path 和 patchelf。
让 VS Code Server 在安装时修补自己的 Node 二进制。
用日志和 ELF interpreter 验证补丁已经真正生效。
保持系统 glibc 2.17 不变，并把该方案定位为迁移前的过渡措施。

在本文参考服务器上，系统仍然报告 glibc 2.17，但 VS Code Server 日志已经显示 Patching glibc、Patching linker 和 Patching complete，Server 内置 Node 也已指向私有 glibc 2.28 的动态链接器。这说明隔离方案能够在不破坏系统基础运行库的前提下恢复远程开发能力。

CentOS 7.9 修复 VS Code Remote-SSH：用私有 glibc 2.28 绕过 glibc 2.17 限制