VS Code Remote SSH 与 WSL
在 Windows 上打开一个 Linux 项目，或者从笔记本连接一台开发机，画面仍然是熟悉的 VS Code，很容易让人误以为“只是文件换了位置”。真正改变的是执行边界：桌面客户端仍在本地，VS Code 会在 SSH 主机或 WSL 发行版中安装与客户端匹配的 VS Code Server；语言服务、调试适配器、终端和多数工作区扩展在目标环境运行；项目进程监听的也是目标环境端口。
Remote SSH 与 WSL 共享这套“本地 UI、目标侧执行”的模型，但入口不同：Remote SSH 先经过主机认证和网络边界，WSL 则进入本机的 Linux 发行版。连接之前，开发主机或 WSL 发行版必须已经由其 owner 建好账号、网络与系统基线；编辑器连接不能替代 sshd 加固、防火墙、发行版备份或生产主机治理。尤其不要用“VS Code 能连上”证明目标主机适合开发。
Remote SSH 也不是文件同步工具。Remote SSH 官方文档明确说明它不会直接把远端源码同步到本地，也不会让本地工具透明处理远端工作区。需要双副本时必须另行设计 rsync、制品传递或 Git 流程，并承担冲突和泄密风险；不要把 VS Code 窗口当成同步协议。
先证明目标环境独立可用
本地安装 VS Code Stable，并确认命令行入口可用：
code --version
ssh -VRemote SSH 需要本地 OpenSSH-compatible 客户端、可认证的 SSH 目标，以及远端可用的 SSH server。远端 Linux 支持基线还要求目标具备匹配的 kernel、glibc 或 musl、libstdc++ 与 tar；Remote SSH 额外依赖 bash、OpenSSH server 以及 curl 或 wget。这些数值会随 VS Code Server 演进，升级时必须重新查询官方矩阵，不能把某次通过的旧发行版永久写进资产基线。WSL 路线要求 Windows 侧已经安装 VS Code，目标发行版能从 wsl.exe 正常进入；不要在 WSL 内再安装一套 Linux 桌面版 VS Code。
连接前先从普通终端证明基础环境成立：
ssh dev-box
wsl.exe --list --verbosedev-box 是示例别名，不是真实主机。预期第一条命令进入获准的开发主机，第二条列出目标发行版及其状态。SSH 本身失败时先处理认证、DNS、代理跳板或主机策略，不要反复重装 Remote - SSH 扩展。
这两个命令只证明 VS Code 之外的基础入口可用。随后每次实验都应记录客户端版本、目标系统、命令退出码和 Remote 输出日志；删除 Server 目录、known_hosts 条目或远端文件前，先确认对象确实属于当前账号与当前实验。
先理解运行链路
主题、窗口装饰等纯 UI 扩展通常留在本地；语言服务、代码检查、调试器等工作区扩展通常安装到目标环境。远程扩展运行模型允许扩展作者声明运行位置，所以最终应以 Extensions 视图的 Local 与 SSH/WSL 分组、扩展详情和实际进程为准。Settings Sync 不会自动把扩展同步到或同步自 SSH、WSL、Dev Container 窗口。
扩展宿主不是权限沙箱。VS Code 扩展运行时安全说明指出，扩展与其所在的 VS Code 进程拥有同等级权限，可以读写文件、联网并启动外部进程。工作区扩展移到 SSH/WSL 后，这份能力也随之移到目标账号；团队允许列表必须同时考虑发布者、版本、原生依赖、外联地址和远端数据可见性，而不能只看本地 Marketplace 已通过签名验证。
Server 与“独立 VS Code Server/Tunnels 服务”也不能混为一谈。Remote SSH/WSL 会自动管理配套 Server；独立 Server 实例面向单用户，其许可也不允许把它改造成通用多人托管服务。需要集中工作区时，应选择具备租户、身份和生命周期模型的平台，而不是共享一个 Server 目录。
Remote SSH
在本地 VS Code 中安装 Microsoft 发布的 Remote - SSH 扩展；也可以安装 Remote Development extension pack，但团队应记录真正需要的扩展，而不是用扩展包掩盖准入清单。安装后先在系统终端验证 SSH，再从命令面板执行 Remote-SSH: Connect to Host...。
本地 ~/.ssh/config 可以保存非敏感连接参数：
Host dev-box
HostName dev.example.com
User devuser
IdentityFile ~/.ssh/id_ed25519_dev
IdentitiesOnly yes仓库里不要提交这段真实值。HostName、用户名、私钥路径、ProxyJump 和内网拓扑都属于本地或组织配置。首次连接要人工核对主机指纹；主机密钥变化时先从可信运维渠道确认轮换，不要直接删除整份 known_hosts。
连接成功后，新的 VS Code 窗口状态栏应显示 SSH: dev-box。首次连接会安装与当前客户端匹配的 Server；随后打开远端仓库根，而不是本地映射盘或随手进入的 home 目录。
WSL
在 Windows 侧 VS Code 安装 Microsoft 发布的 WSL 扩展。进入目标发行版和仓库目录后执行：
cd ~/src/your-project
code .预期 Windows 侧 VS Code 打开新窗口，状态栏显示目标 WSL 发行版，首次启动提示安装匹配的 VS Code Server。此时集成终端应是 Linux shell，语言扩展需要安装在 WSL 分组中。
代码虽然可以放在 /mnt/c，但大量小文件、文件监听、权限位和大小写敏感项目通常更适合放在 WSL 的 Linux 文件系统中。不要在 Windows 与 WSL 两侧分别对同一工作树运行包管理器；原生依赖、文件权限和缓存会互相污染。
最小验证：证明命令、调试和端口都在目标侧
先在远程窗口终端执行：
pwd
uname -a
git rev-parse --show-toplevel
printf 'context=%s\n' "${WSL_DISTRO_NAME:-ssh-host}"预期路径属于 SSH 主机或 WSL，Git 根与打开的工作区一致。若 pwd 指向 Windows 路径、错误仓库或 home 目录，先重新打开正确文件夹。
再验证项目运行时。下面以已经安装 Node.js 的项目为例；没有 Node.js 时换成项目真实运行时，不要为了教程临时污染远端基线：
node --version
which node预期 which node 指向目标环境。随后用临时目录启动一个仅用于端口验证的 HTTP 服务：
mkdir -p /tmp/vscode-remote-check
printf 'remote-ok\n' > /tmp/vscode-remote-check/index.html
cd /tmp/vscode-remote-check
python3 -m http.server 3000 --bind 127.0.0.1在 VS Code Ports 视图转发 3000，从本地浏览器访问 VS Code 给出的本地地址。预期页面只显示 remote-ok。不要把调试端口、数据库管理端口或内部服务改成公开可见；Remote SSH 的本地转发与云平台公开端口不是同一权限模型。
调试应使用仓库已有、无凭证的 .vscode/launch.json。启动一次项目调试，确认断点命中后，在 Debug Console 或程序日志中输出当前工作目录和平台。预期目标进程、调试适配器及源码路径都在 SSH/WSL 侧。路径显示本地盘符或断点灰色时，先检查扩展安装位置和 cwd，不要先复制源码。
验证完按以下顺序清理：停止调试；在运行 HTTP 服务的终端按 Ctrl+C；删除 /tmp/vscode-remote-check；从 Ports 视图停止转发；执行 File: Close Remote Connection 或关闭远程窗口。最后在目标环境确认端口已经释放：
ss -ltn | grep ':3000 ' || true
rm -rf /tmp/vscode-remote-checkgrep 没有输出表示没有进程继续监听该端口。这里的 rm -rf 只针对固定实验目录；不要把变量拼进删除命令。
接入真实项目
远程开发不是给现有项目再造一套构建系统。第一原则仍是：项目在目标环境的普通终端能够从干净 clone 构建、测试和启动，VS Code 只消费这条事实链。
团队文档应写清推荐入口、仓库根、目标运行时、构建命令、需要安装在远端的扩展、启动端口和退出语义。例如一个 Linux 服务可以规定：Windows 开发统一从 WSL 的 ~/src 打开；大仓或专用硬件项目统一连开发主机；.vscode/tasks.json 调用仓库 wrapper；.vscode/launch.json 只引用环境变量名称，不保存真实值。
远端窗口中重新执行项目的 CLI 基线：
git status --short
./gradlew test
# 或 npm ci && npm test只选择仓库实际支持的一条命令。预期结果应与 CI 基线一致，且执行路径、运行时和缓存都属于目标环境。若 CLI 失败而 IDE 看似正常，先修项目环境；若 CLI 成功而语言服务报错，检查扩展位置、项目根、解释器和远端设置。
日常提效不等于隐藏执行位置
Remote SSH 可以保存主机别名和最近目录，WSL 可以从发行版终端用 code . 直达仓库；两者都可以用任务、调试、端口自动转发和远端设置减少重复操作。但每个快捷入口都要保留上下文证据：状态栏、终端提示、当前分支、运行时版本和端口来源。
适合共享的是无密钥项目设置、任务和调试模板。适合留在个人层的是字体、主题、主机别名和本地 SSH agent。主机特定 Remote Settings 可覆盖本地 User Settings，Workspace Settings 又可继续覆盖它；出现“只有某台主机行为不同”时，应按这条优先级查配置，而不是全量复制 settings.json。
对于大仓，代码、依赖缓存和索引都留在远端本地磁盘，通常比 SSHFS 批量读写更稳定。SSHFS 适合少量文件交换，不应让本地 Git、构建器或索引器跨网络扫描整个远端仓库。
代理、端口与下载链路
远程连接至少包含三条网络链路：本地 VS Code/Marketplace、SSH 到目标主机、目标环境下载 Server、扩展和项目依赖。某一条能联网不能证明其余链路可用。
Remote SSH 默认尝试让远端下载 Server，失败后可以回退为本地下载再通过 SSH 传输；受限网络可评估 remote.SSH.localServerDownload，但仍要按官方当前域名清单配置 HTTPS 出站。扩展市场安装可能同时要求本地客户端和远端 Server 访问相应端点。离线安装 VSIX 时要验证来源、签名、版本和目标平台，不能把个人下载目录当团队仓库。
项目依赖代理应配置在真正执行下载的目标环境：WSL 中的 npm/Maven/Git 代理配在 WSL，SSH 主机上的构建代理配在 SSH 主机。不要为了快速恢复永久关闭 TLS 校验。企业 CA 需要分别进入 Windows、本地 VS Code、WSL/SSH 系统信任、语言运行时和包管理器的正确证书链。
端口转发默认只应服务当前开发者本机。转发前记录目标进程、容器或主机、端口用途和数据敏感度；结束后同时停止转发与目标进程。WSL 中 Windows 通常可通过 localhost 访问 Linux 服务，但绑定地址、镜像网络模式、VPN 和企业安全软件会改变结果。需要从局域网访问时属于新的暴露决策，不能沿用“本机 localhost 很安全”的判断。
SSH 权限与凭证
Remote SSH 使用的是本地 SSH 客户端及其配置。私钥应由系统密钥环、受控文件权限或硬件密钥保护，仓库只保存主机别名说明，不保存私钥、密码和真实内网地址。优先使用短期 SSH 证书或可撤销身份；长期静态密钥必须有 owner、用途、轮换和离职回收记录。
SSH agent forwarding 能让远端进程借用本地 agent 签名，但取得远端用户权限的攻击者可能在转发会话期间滥用 agent。只有确实需要从远端拉取私有仓库时才对指定主机启用，并优先使用受限、短期、需要触摸确认的密钥。不要把生产云密钥、kubeconfig 或通用 PAT 复制进远端 home 目录来换取便利。
主机信任与用户认证是两件事：known_hosts 防止连错主机，私钥或证书证明用户身份。主机指纹变化不能用“能重新登录”证明安全；必须从独立可信渠道核验。
WSL 不需要 SSH 登录，但同样有凭证分层。Windows Credential Manager、WSL 内 Git credential helper、SSH agent 和环境变量不是自动等价的。团队要选一种受支持的桥接方式并验证撤销，不要让凭证在 Windows 与多个发行版中形成无法盘点的副本。
常见失败：沿执行链定位
一直停在 Installing VS Code Server
先打开 Remote-SSH: Show Log，判断失败发生在 SSH 登录、远端下载、本地下载传输、解压还是 Server 启动。再在远端检查磁盘、home 写权限、tar、bash、curl/wget 和代理。修复基础条件后执行 Remote-SSH: Kill VS Code Server on Host 再连接。反复删除 Server 而不保存日志，只会丢失根因证据。
Server 启动后立即退出
记录 uname -m、kernel、ldd --version 和 libstdc++ 能力。glibc 低于当前基线、旧版 RHEL/CentOS、磁盘 noexec、home 配额不足或 shell 启动脚本输出异常都可能阻断 Server。自备 sysroot 是官方标注的非支持迁移办法，不应成为长期生产开发基线。
扩展本地可用，远端窗口不可用
在 Extensions 视图区分 Local 与 SSH/WSL 分组，检查扩展是否属于 Workspace Extension、是否已安装到目标环境、是否包含匹配 CPU 与 libc 的原生二进制。ARM 与 Alpine/musl 的失败常来自扩展自身打包，而不是 VS Code Server。
终端版本正确，任务或调试版本错误
检查任务 options.cwd、launch.json 的 cwd/runtime、远端设置和 shell 初始化。非交互 shell 不一定读取与交互终端相同的 profile。把版本输出加入任务前置验证，比在 PATH 中继续堆目录更可审计。
端口已转发但浏览器打不开
先在目标环境执行 ss -ltnp，确认服务确实监听预期地址和端口；再检查 Ports 视图映射；最后检查本地端口冲突、VPN 与浏览器代理。目标进程只监听容器内部地址时，还要进入对应容器网络排查，不能把 Remote SSH 转发当成容器端口发布。
WSL 项目持续卡顿或文件权限异常
先判断仓库位于 Linux 文件系统还是 /mnt/c，再检查是否由 Windows 与 Linux 两侧工具同时写入。把仓库迁回 WSL home、删除可重建的错误平台依赖并由 WSL 包管理器重装，通常比调整编辑器文件监听上限更接近根因。WSL 安装、磁盘压缩和发行版修复转交开发机基础专题。
架构取舍
本地开发最简单，适合工具链可直接安装、数据可留在开发机的项目。WSL 适合 Windows 主机上的 Linux 工具链，延迟低、离线能力好，但仍共享一台物理机的 CPU、磁盘和凭证边界。Remote SSH 适合大仓、专用硬件、内网依赖或统一算力；代价是网络可用性、远端账号、磁盘配额、Server 兼容和主机多租户风险。
不要用 Remote SSH 直接编辑生产主机。开发主机应与生产隔离，具备可重建镜像、普通用户权限、资源配额、审计和销毁周期。多人共用一个 Unix 账号会让 Server 目录、扩展、Git 身份和进程归属全部失真；官方 Server 也按单用户模型设计。
如果团队需要把工具链作为仓库定义，并希望本地与云工作区消费同一规范，继续阅读 Dev Containers 工程手册。如果只是需要 Windows 上的 Linux 兼容层，不要为了“更标准”额外叠容器；每加一层都会增加文件系统、网络、用户和凭证映射。
彻底清理与退出
日常退出只需停止项目进程、关闭端口转发并执行 File: Close Remote Connection。这会断开窗口，但不保证删除 Server、扩展、源码、构建缓存或凭证。
需要重装 Remote SSH Server 时，先保存日志，然后执行 Remote-SSH: Kill VS Code Server on Host。若命令无法工作，断开后在已确认的远端用户 home 中检查并删除该用户的 .vscode-server 或 Insiders 对应目录；目录名和布局可能随版本变化，应以官方当前故障文档和实际日志为准。删除会移除远端 Server 与远端扩展，下次连接重新下载，不会替你删除源码和项目缓存。
WSL 中同样要先关闭所有 VS Code WSL 窗口，再在目标发行版确认 Server 进程和目录。只清理 VS Code Server，不注销发行版、不删除 Linux home，也不动项目仓库。WSL 发行版的彻底删除属于系统级破坏操作，不是 IDE 清理步骤。
最后按责任逐项处理：卸载本地 Remote - SSH/WSL 扩展；从本地 SSH config 删除不再使用的别名；仅在已核验主机退役或重建后用 ssh-keygen -R <host> 删除对应主机键；撤销 SSH 证书和临时 token；删除实验目录；确认端口不再监听；按团队保留策略清理远端源码、构建缓存和日志。任何共享开发主机清理都必须由 owner 审批，不能直接 rm -rf ~/.vscode-server 影响同一账号下的其他会话。
团队治理与长期维护
团队基线至少记录 VS Code 通道、Remote 扩展版本策略、支持的 SSH/WSL 平台、代表性扩展、Server 下载路径、代理与 CA、端口默认可见性、账号 owner、磁盘配额和退出清理。升级先在代表主机验证连接、扩展激活、构建、断点和端口，再扩大范围。
每次故障单应包含本地 VS Code 版本/commit、Remote 扩展版本、连接类型、目标 OS/CPU/libc、状态栏上下文、远端运行时、扩展安装位置和脱敏日志。没有这些证据，“远程开发坏了”无法区分客户端升级、Server 残留、扩展原生依赖、代理还是项目本身。
新人准入不能停在“能看到代码”，而要从干净身份连接开发环境，打开正确仓库，完成 CLI 构建、一次断点、一次本地端口访问，再安全退出并证明端口、临时进程和凭证都已回收。做到这一步，Remote SSH 与 WSL 才从个人技巧变成可治理的开发入口。
能画出本地 UI、Server、扩展宿主、代码、运行时和端口所在位置。SSH/WSL 基础入口先于 VS Code 验证，目标平台满足当前官方支持基线。项目 CLI、调试和端口转发均在目标环境验证，并有预期结果。
代理、CA、Marketplace、Server 下载和项目依赖链路分别检查。私钥、主机信息、PAT、kubeconfig 和真实服务地址未进入仓库与同步设置。日常断开、Server 重装、源码/缓存清理和凭证撤销有不同操作边界。
代表性扩展在目标 CPU/libc 上经过验证，升级与退出均有 owner。