VS Code Remote-SSH：从日志到扩展宿主的排查

Remote-SSH 不是一个单进程功能。至少包含：本地 VS Code、SSH 客户端、远端 shell、VS Code Server，以及在本地或远端运行的扩展。排障时先确认失败发生在哪一层。

1. 先看 Remote-SSH 日志

在 VS Code 中打开：

View → Output → Remote - SSH

记录第一处明确错误，不只截最后一个弹窗。官方也建议从该输出通道获取详细连接日志：Remote Development using SSH。

然后在系统终端验证同一目标：

ssh -vvv -p SSH_PORT HOST_ALIAS

若系统终端也失败，先解决 SSH；若系统终端成功而 VS Code 失败，再检查 VS Code 使用的配置文件、SSH 可执行文件和远端 Server。

2. SSH 配置使用别名

Host RESEARCH_HOST
    HostName SERVER_HOST
    User USER_NAME
    Port SSH_PORT
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes

私钥只保留在本地受控位置，不复制到远端，也不提交到仓库；示例配置使用占位用户、主机名和路径。

查看最终生效配置：

ssh -G RESEARCH_HOST

3. 本地扩展与远端扩展

~/.vscode/extensions：当前机器的本地 VS Code 扩展；
~/.vscode-server/extensions：Remote-SSH 目标机上的远端扩展。

界面类扩展通常在本地运行，语言服务、调试器和需要读取远端工作区的扩展通常在远端运行。CPU 占用高时先在 VS Code 的“正在运行的扩展”视图确认是哪个扩展宿主，不要直接删除整个扩展目录。

远端只读检查：

ps -ef | grep -i '[v]scode'
du -sh ~/.vscode-server

设置同步不等于同步远端环境

VS Code 内置 Settings Sync 可以同步用户设置、快捷键、Profile 和本地安装的扩展。机器相关设置默认不应同步；Remote-SSH、WSL 或容器窗口里的远端扩展也不会因此自动复制到另一台远端主机。

开启前先确认登录账号和同步范围。发生冲突时使用“Show Conflicts”比较本地与远端内容，不要在没看差异时直接覆盖。同步日志可在 Output 中选择 Settings Sync 查看。详见 Settings Sync。

4. 远端 Server 启动失败

核对：

uname -a
df -h
df -ih
command -v bash tar curl wget

常见边界包括：

远端系统或 glibc 已低于当前 VS Code Server 要求；
主目录空间或 inode 耗尽；
shell 启动脚本输出了交互内容；
代理只能在交互 shell 中生效；
下载目录或临时目录没有执行/写入权限。

当前最低要求会变化，应查 VS Code 官方系统要求，不要继续把 Ubuntu 18.04 当作默认受支持环境。

5. Python 解释器与 Code Runner

先在 VS Code 状态栏选择项目解释器，再在集成终端验证：

python -c 'import sys; print(sys.executable)'
python -m pip --version

如果使用 Code Runner，脚本 shebang 可能影响实际执行器。项目代码更推荐通过 Python 扩展的“Run Python File”或终端显式运行：

python path/to/script.py

若确实要让 Code Runner 忽略 shebang，可在工作区设置中确认 code-runner.respectShebang 的行为；这不是修复解释器混乱的替代方案。

6. 常用界面设置

分散的快捷键设置可以集中为一段可搜索、可回滚的用户配置：

{
  "editor.fontSize": 15,
  "terminal.integrated.fontSize": 14,
  "editor.mouseWheelZoom": true,
  "terminal.integrated.cursorStyle": "line",
  "editor.insertFinalNewline": true
}

editor.fontSize 与 terminal.integrated.fontSize 分别控制编辑区和集成终端；
editor.mouseWheelZoom 允许按住修饰键滚轮缩放编辑器；
terminal.integrated.cursorStyle 可使用当前版本设置界面列出的值；
文本文件末尾换行通常是 POSIX 和代码仓库的良好约定，不建议仅因视觉偏好全局关闭。若特定生成文件要求无末尾换行，应在生成器或项目规则中处理。

侧栏和整个 UI 的缩放可从命令面板运行 View: Zoom In、View: Zoom Out、View: Reset Zoom。终端面板的位置可通过 View/Appearance 或面板标题栏菜单调整。菜单名称可能变化，优先在命令面板搜索动作，不修改程序安装目录里的 CSS。

用户设置、远端设置和工作区设置有优先级差异。只与某个项目有关的排除规则、格式化器和解释器选择应写在工作区；字体和主题通常放在用户或 Profile 设置中。工作区来自不可信仓库时，先查看它声明的任务、调试配置和可执行程序路径。

7. 文件比较、搜索与文本变换

下面这些需求可以直接通过内置功能完成：

比较两个文件：在 Explorer 对第一个文件选择 Select for Compare，再对第二个选择 Compare with Selected；
比较当前文件和已保存版本：命令面板运行 File: Compare Active File with Saved；
限定目录搜索：在 Search 视图的“files to include”填写工作区相对目录或 glob；
大小写转换：选中文本后在命令面板搜索 Transform to Uppercase / Transform to Lowercase；
查看文件大小：系统属性、ls -lh 或 PowerShell Get-Item 已足够时，不必额外安装能读取整个工作区的扩展。

VS Code 官方还支持与剪贴板、工作区文件比较，见 Basic editing: Compare files。

8. 远端文件传输

连接 Remote-SSH 后，Explorer 中的文件拖放可用于少量文件操作，但它不等于可靠的大规模同步。批量传输、断点续传或可审计部署优先使用 scp、sftp、rsync 或版本控制，并在传输后校验数量、大小或哈希。

VS Code 官方也明确说明 Remote-SSH 不直接提供源码同步；需要本地工具批量读写远端树时，可评估 SSHFS 或 rsync。不要把生产服务器目录当作本地工作区随意拖拽覆盖。

9. 扩展和缓存占用空间

先只读查看，再决定是否处理：

du -sh ~/.vscode ~/.vscode-server 2>/dev/null
du -sh ~/.vscode-server/extensions/* 2>/dev/null | sort -h | tail
code --list-extensions --show-versions

区分本地扩展、远端扩展、Server 版本、日志和项目自己的构建缓存。应通过 Extensions 界面卸载不用的扩展；不要直接删除整个 ~/.vscode-server 或复制/覆盖系统 OpenSSH。多用户远端还要确认目录所有者，避免替别人清理。

10. 大型工作区与文件监视

不要直接扩大系统监视器上限作为第一步。先排除无需索引的目录：

{
  "files.watcherExclude": {
    "**/.git/objects/**": true,
    "**/build/**": true,
    "**/logs/**": true,
    "**/node_modules/**": true
  },
  "search.exclude": {
    "**/build/**": true,
    "**/logs/**": true
  }
}

再确认是否仍有实际监视需求。

若 Remote-SSH 的 Node/extension host 长时间占满 CPU，先在命令面板运行 Developer: Show Running Extensions，记录具体扩展与宿主；必要时使用 Help: Start Extension Bisect 做二分排查。远端同时结合 ps 查看进程，但不要仅凭进程名杀死所有 node，服务器上可能有别的 Node 服务。

11. 安装与旧系统边界

VS Code 本体、Remote-SSH 和扩展只从 VS Code 官方下载页与官方 Marketplace 获取。Ubuntu 18.04 等旧系统可能低于当前 VS Code Server 的 glibc/libstdc++ 要求；这不是“换一个 .deb 依赖链接”就能稳定解决的问题。需要维护旧环境时，先查当前 Remote Development Linux requirements，再决定升级系统、固定旧客户端或使用隔离环境。

12. 旧故障现场与已删除的修复

下面两张故障截图分别记录 VS Code Remote-SSH 安装脚本返回异常和 Windows 端 SSH 进程提前退出。它们可以帮助辨认故障层级，但截图本身不能证明系统 OpenSSH 已损坏。

VS Code Remote-SSH 安装脚本返回异常的旧故障截图

Windows 端 SSH 进程提前退出的旧故障截图

有一种做法是从另一台 Windows 电脑复制并替换 C:\Windows\System32\OpenSSH。它没有找到根因，还可能引入版本、签名和系统文件完整性问题，因此本文不建议这样处理。正确方向是检查 VS Code 日志、ssh -vvv、Windows 可选功能/系统更新以及实际使用的 ssh.exe 路径。

参考资料与书签

以下 24 条仅作为历史检索入口。第三方教程的菜单、扩展行为、最低系统要求和修复方法可能已经变化；不要照抄删除缓存、替换系统 OpenSSH 或在不核对差异时覆盖远端文件。