VS Code 远程开发

通过 Visual Studio Code 连接开发机，可获得完整智能感知、代码导航与断点调试、集成终端一体化，实现几乎本地般的开发体验。

先决条件

• 安装 VS Code（稳定版或 Insiders）：https://code.visualstudio.com/download
• 本机有可用的 OpenSSH 客户端
  • macOS 自带；Windows 推荐安装下列其一：
    • Windows OpenSSH：https://learn.microsoft.com/windows-server/administration/openssh/openssh_install_firstuse
    • Git for Windows：https://git-scm.com/download/win
• 能用平台提供的 SSH 命令在本机成功登录远端一次（密码或密钥均可），详见开发机 SSH 远程登录。

添加开发机为 SSH 远程主机

以下介绍如何使用 VS Code 连接并开发 AI Studio 的开发实例。

Step 0 登录平台选择开机的实例

1. 在智算云平台选择开发机，确保实例已开机且可 SSH。
2. 访问开发机列表页面（或详情页面），复制平台提供的 SSH 连接命令（例如：ssh -p 44851 root@111.51.90.14）。

注意

开发机支持 SSH 密码认证或密钥认证。若已启动密码认证，可从开发机详情页复制 SSH 密码。

Step 1 本地 VS Code 配置 Remote - SSH

1. 打开本地的 VS Code 开发插件菜单，在扩展程序市场中搜索安装 Remote - SSH 扩展。

2. 打开命令面板（Cmd/Ctrl+Shift+P），输入 "Remote - SSH: Add New SSH Host…" ，粘贴从平台复制的开发机 SSH 连接命令，选择要写入的 ssh_config 文件。扩展会在您指定的 ssh_config 文件中生成以下等效配置（示例）：

   Host 111.51.90.14
       HostName 111.51.90.14
       Port 44851
       User root

3. 首次连接时可直接连接或打开配置。强烈建议打开配置文件，手动修改 Host 字段为更有意义的名称，以避免后续 Host 名称冲突。

Step 2 SSH 连接并登录开发机实例

1. 打开本地的 VS Code，点击左侧 Remote Explorer 图标，选择刚添加的 SSH 主机进行连接。

2. 首次连接时会自动在远端开发机上安装 VS Code Server 于远端主机。如提示指纹确认、密码/密钥口令（passphrase），按提示完成。

   注意

   默认情况下，Remote - SSH 会尝试在远程主机上下载 VS Code Server；如果失败，则在连接建立后回退为先在本地下载 VS Code Server 并将其传输到远程。您可以通过 remote.SSH.localServerDownload 设置来更改此行为：可以调整为 always（始终在本地下载后再传输），或 off（从不回退到本地下载）。

3. 连接成功后，左下角状态栏会显示远端主机名，窗口即为远程窗口。

Step 3 打开代码目录

在远程窗口中使用 File > Open Folder… 打开远端代码目录或工作区，开始像本地一样编辑、运行与调试。

更细致的指导步骤,可参考以下教程：

📖 VS Code 远程开发：为开发机、AICoder 提供本地般的开发体验

配置终端自动进入 tmux 会话（推荐）

在进行模型训练等长时间任务时，SSH 连接可能会因网络波动或电脑休眠而断开。为了避免中断正在运行的终端任务，推荐使用 tmux 保持会话持久化。

方案一：基础配置（适合大多数用户）

最简单的方式是将 VS Code 的默认终端设置为 tmux。这样每次新建终端时，都会自动启动 tmux。

1. 确保开发机已安装 tmux (apt install tmux 或 yum install tmux)。
2. 在 VS Code 终端下拉菜单中选择 "Select Default Profile"，如果列表中有 tmux，直接选择即可。

方案二：进阶配置（适合重度用户）

如果您需要在多个工作区（Workspace）之间切换，或者希望终端能自动根据主机名+目录名管理会话，可以使用以下进阶配置。

提示

本方案中的 JSON 配置是一个可用的 Demo 配置，旨在展示如何通过 VS Code 设置实现复杂的会话管理。您可以直接使用，也可以以此为基础，根据自己的工作流定制最适合的方案。

此配置提供了三个功能强大的 Profile：

1. 自动挂载 (Attach)：按 主机名-目录名 自动连接或创建会话。
2. 新建会话 (New)：强制创建新会话（自动递增编号）。
3. 交互选择 (Picker)：使用 fzf 交互式选择要进入的会话。请确保开发机已安装 fzf (apt install fzf 或 yum install fzf)。

配置方法：

1. 连接到远程开发机后，打开命令面板 (Cmd/Ctrl+Shift+P)，输入并选择 "Preferences: Open Remote Settings (JSON) (SSH: ...)"。

   重要

   配置位置：务必确保选项中带有 Open Remote Settings (JSON) 字样，以编辑远端主机上的设置。不要写到本地 User Settings 或 Workspace Settings。

2. 在打开的 settings.json 文件中添加以下配置：

   {
   "terminal.integrated.enablePersistentSessions": true,
   
   "terminal.integrated.profiles.linux": {
       "tmux-attach-workspace": {
       "path": "/usr/bin/bash",
       "args": [
           "-lc",
           "set +e; HOST=\"${TMUX_HOST_ALIAS:-$(hostname | cut -d. -f1)}\"; WS=\"$(basename \\\"${VSCODE_WORKSPACE_FOLDER:-$PWD}\\\")\"; WS=\"$(printf '%s' \\\"$WS\\\" | tr -cs 'A-Za-z0-9._-' '_' | sed -E 's/_+/_/g; s/^[_-]+//; s/[_-]+$//')\"; SESSION=\"$HOST-$WS\"; tmux new-session -A -s \"$SESSION\" || { echo \"tmux attach/create failed\"; echo \"SESSION=$SESSION\"; exec bash -l; }"
       ]
       },
   
       "tmux-new-session": {
       "path": "/usr/bin/bash",
       "args": [
           "-lc",
           "set +e; HOST=\"${TMUX_HOST_ALIAS:-$(hostname | cut -d. -f1)}\"; WS=\"$(basename \\\"${VSCODE_WORKSPACE_FOLDER:-$PWD}\\\")\"; WS=\"$(printf '%s' \\\"$WS\\\" | tr -cs 'A-Za-z0-9._-' '_' | sed -E 's/_+/_/g; s/^[_-]+//; s/[_-]+$//')\"; BASE=\"$HOST-$WS\"; NAME=\"$BASE\"; i=2; while tmux has-session -t \"$NAME\" 2>/dev/null; do NAME=\"$BASE-$i\"; i=$((i+1)); done; tmux new-session -s \"$NAME\" || { echo \"tmux new-session failed\"; echo \"NAME=$NAME\"; exec bash -l; }"
       ]
       },
   
       "tmux-picker": {
       "path": "/usr/bin/bash",
       "args": [
           "-lc",
           "set +e; command -v fzf >/dev/null 2>&1 || { echo \"fzf not installed. Run: sudo apt install fzf\"; exec bash -l; }; HOST=\"${TMUX_HOST_ALIAS:-$(hostname | cut -d. -f1)}\"; WS=\"$(basename \\\"${VSCODE_WORKSPACE_FOLDER:-$PWD}\\\")\"; WS=\"$(printf '%s' \\\"$WS\\\" | tr -cs 'A-Za-z0-9._-' '_' | sed -E 's/_+/_/g; s/^[_-]+//; s/[_-]+$//')\"; BASE=\"$HOST-$WS\"; NEW='[new] '; ATT='[attach] '; sessions=$(tmux ls -F '#S' 2>/dev/null || true); choices=$(printf \"%s\\n%s\\n\" \"${NEW}${BASE}\" \"$sessions\" | sed '/^$/d' | awk -v p=\"$ATT\" 'NR==1{print;next}{print p $0}'); sel=$(printf \"%s\\n\" \"$choices\" | fzf --prompt='tmux> ' --height=40% --reverse); [ -z \"$sel\" ] && exec bash -l; if [[ \"$sel\" == \"$NEW\"* ]]; then NAME=\"$BASE\"; i=2; while tmux has-session -t \"$NAME\" 2>/dev/null; do NAME=\"$BASE-$i\"; i=$((i+1)); done; exec tmux new-session -s \"$NAME\"; else SESSION=$(printf \"%s\" \"$sel\" | sed -E 's/^\\[attach\\] //'); exec tmux attach -t \"$SESSION\"; fi"
       ]
       }
   
   },
   
   "terminal.integrated.defaultProfile.linux": "tmux-attach-workspace"
   }

进阶配置说明

• tmux-attach-workspace (默认)：自动根据当前主机名和工作区目录名生成会话名称（如 host-workspace）。如果会话存在则自动 Attach，否则创建新会话。这是最常用的模式。
• tmux-new-session：强制创建一个新的 tmux 会话，名称末尾会自动添加序号以避免冲突。当您需要一个全新的环境而不干扰现有会话时使用。
• tmux-picker：交互式选择器（需要安装 fzf）。启动时会列出所有现有的 tmux 会话供您选择 Attach，或者选择创建新会话。

注意

平台预置镜像通常已预装 tmux。如果要使用 tmux-picker，请确保开发机已安装 fzf (apt install fzf 或 yum install fzf)。

最佳实践与常见问题

• 作用边界：无论哪种方案，都主要解决 SSH 断线 / VS Code 重载导致的终端状态丢失；如果开发机关机/重启，tmux 会话也会消失。
• 保持单行命令：进阶方案中的 JSON 配置不支持字符串拼接或反斜杠续行，请保持命令为单行字符串。
• 终端闪退排查：进阶方案已包含 exec bash -l 兜底机制，如果终端一闪而过，通常会回退到 shell 并显示错误信息（如缺少 fzf）。
• 避免嵌套：自动进入 tmux 会话后，不建议在其中再次手动运行 tmux 命令。

了解更多关于 tmux 和后台运行的知识：

📖 Linux 后台运行：掌握 nohup、tmux 和 screen

在 VS Code Notebook 跑长任务：该怎么选？

在远程开发中使用 Jupyter Notebook 时，最常见的问题是：网络断开或 VS Code 重载是否会中断我的训练？

VS Code 的 Jupyter 内核通常依赖于编辑器会话。为了保证长任务的可靠性，建议根据任务时长选择不同的工作流：

决策建议

任务类型	推荐方案	理由与风险提示
快速探索 (小于 1 小时)	直接使用 VS Code Notebook	简单快捷，享受完整的 IDE 智能提示和功能。风险提示：此方式严重依赖 SSH 连接稳定性。网络波动或长时间无操作导致的 SSH 断开将直接杀死训练进程。
长时训练 (大于 1 小时)	方案 A：tmux + Jupyter Lab (VS Code 连接远程内核)	最稳健。Jupyter Server 在 tmux 后台运行，完全独立于 VS Code 会话。即使本地关机、断网或 SSH 超时断开，训练进程依然存活。
生产级任务 (高成本/关键)	方案 B：tmux + Python 脚本 (配合 Checkpoint)	相比 Notebook，脚本更易于记录日志和版本控制。务必在代码中加入断点续训 (Checkpoint) 机制，确保数据安全。

方案 A 实现指引

核心思路是解耦：让 Jupyter Server 在远程主机的 tmux 中独立运行，VS Code 仅作为前端界面连接它。

1. 远程启动：在 SSH 终端（或 tmux 会话）中启动 Jupyter Lab：

   # 关键：Jupyter Server 需要运行在持久化会话中（例如 tmux），否则断线/重载时仍可能中断
   tmux new -s jupyter 'jupyter lab --no-browser --port=8888 --allow-root'

2. 本地连接：在 VS Code 中运行命令 "Jupyter: Specify Jupyter Server for Connections"，输入远程 Server 的 URL（含 Token）。
3. 开始工作：打开 .ipynb 文件，内核选择刚才连接的远程 Server。

详细操作步骤，请参考：

📖 在 AIStudio 开发机上安装和使用 Jupyter Lab

共享本地代理服务至远程主机

在远程开发时，您可能希望让远程开发机使用本地的网络代理服务，而无需在每台远程主机上单独配置代理。通过 SSH 远程端口转发 (Remote Port Forwarding)，可以将本地运行的服务暴露给远程主机，让远程主机像访问自己的 localhost 一样访问这些服务。

注意

平台不提供网络代理服务，不对通过代理服务与软件访问外网的质量和对端网站的服务质量负责。禁止使用此类服务进行非法活动。

问题场景

您本地已经配置了 VPN 或 HTTP 代理（如 Clash、V2Ray 等），希望远程开发机也能使用这个代理访问外网资源。例如，在 Remote - SSH 连接开发机时，让 GitHub Copilot、Cursor 等服务通过代理访问网络。

解决方案选择：

1. 使用 SSH 远程端口转发共享本地代理（本文方案）

   • 优点：配置一次，所有远程主机复用本地代理
   • 缺点：依赖 SSH 连接，断开后代理失效

2. 在每台远程开发机上安装代理软件（如 Clash）并单独配置

   • 优点：每台机器独立运行，不依赖本地连接
   • 缺点：需要重复安装配置，管理成本高

如需在远程主机上安装 Clash 等代理软件，请参考：

📖 第三方学术加速服务指南

适用场景

• 本地已配置 VPN/HTTP 代理服务，希望远程开发机复用
• 避免在每台远程主机上重复安装和配置代理工具
• 临时性让远程主机访问本地网络资源或服务

注意

SSH 远程端口转发与本地端口转发是相反的方向：

• 本地端口转发 (-L/LocalForward)：将远程服务映射到本地访问
• 远程端口转发 (-R/RemoteForward)：将本地服务暴露给远程主机访问

配置远程端口转发

以下步骤说明如何配置 SSH 使远程主机能够使用本地代理服务。

编辑 SSH 配置文件

编辑 ~/.ssh/config 文件，在开发机的 Host 配置中添加 RemoteForward 指令：

Host dev-server
    HostName 8.140.242.203
    User root
    Port 45560
    RemoteForward 127.0.0.1:7897 127.0.0.1:7897  
    ExitOnForwardFailure yes
    ServerAliveInterval 30
    ServerAliveCountMax 3

注意

示例中使用 7897 作为端口号。请根据您本地代理服务的实际监听端口进行调整（如 Clash 默认为 7890，V2Ray 常用 10808 等）。

参数说明：

• RemoteForward 127.0.0.1:7897 127.0.0.1:7897
  • 第一个 127.0.0.1:7897：远程主机上监听的地址和端口
  • 第二个 127.0.0.1:7897：本地机器上服务的地址和端口
• ExitOnForwardFailure yes：如果端口转发失败，SSH 连接直接退出，避免静默失败

使用配置连接

保存配置后，使用 VS Code 或 Cursor 的 Remote - SSH 扩展连接到开发机。连接建立后，远程端口转发会自动生效。

或者通过命令行连接：

ssh dev-server

验证端口转发

配置完成后，需要验证远程主机是否能正常访问本地代理服务。

Step 1 确保本地代理服务正在运行

在本地机器上确认代理服务已启动并监听在 127.0.0.1:7897：

# 检查本地端口是否在监听
lsof -i :7897
# 或
netstat -an | grep 7897

Step 2 在远程主机上测试连接

连接到开发机后，在远程终端中测试是否能访问 localhost:7897：

# 测试端口是否可达
curl -v http://127.0.0.1:7897

# 或测试代理功能（如果是 HTTP 代理）
curl -x http://127.0.0.1:7897 https://www.google.com

如果返回正常响应，说明远程端口转发配置成功。

配置 VS Code 使用代理

远程端口转发生效后，还需要配置 VS Code 才能让编辑器和扩展使用代理。

配置 VS Code 核心代理设置

在 VS Code 中打开设置 (Cmd/Ctrl+,)，搜索 "proxy"，配置以下核心设置：

1. Http: Proxy (http.proxy)

   设置代理服务器地址：

   "http.proxy": "http://127.0.0.1:7897"

2. Http: Proxy Support (http.proxySupport)

   控制 VS Code 如何应用代理。建议设置为 override（特别是本地代理服务包含流量分流规则时）：

   "http.proxySupport": "override"

   可选值及说明：

   • off：不使用代理
   • on：使用配置的代理
   • fallback：仅在直连失败时使用代理
   • override：推荐。强制所有 HTTP(S) 请求使用代理，确保代理规则生效

   注意

   如果您的代理服务配置了复杂的流量分流规则（如按域名、按协议等），使用 override 可确保所有流量都经过代理服务处理，从而正确应用这些规则。其他选项可自由探索尝试。

3. Http: Use Local Proxy Configuration (http.useLocalProxyConfiguration)

   是否读取系统级代理配置：

   "http.useLocalProxyConfiguration": false

应用范围说明

这些设置是 VS Code 核心设置，会影响：

• VS Code 本身的网络请求（扩展市场、更新检查、设置同步等）
• 使用 VS Code 网络 API 的扩展

但不会影响：

• 自行实现网络功能的扩展
• 在远程终端中直接运行的命令

对于后者，需要在远程主机上设置环境变量：

export http_proxy=http://127.0.0.1:7897
export https_proxy=http://127.0.0.1:7897

适用于 VS Code 和 Cursor

此配置作用于底层 SSH 连接，因此对 VS Code 和 Cursor 均有效。两者都基于 Remote - SSH 扩展，共享相同的 SSH 配置文件 (~/.ssh/config)。

相关参考：

📖 VS Code 远程开发：为开发机、AICoder 提供本地般的开发体验

📖 SSH 端口转发：公网访问开发机内 HTTP 服务

手动安装 VS Code Server 端组件

在首次连接时，VS Code 会尝试在远程主机上下载 Server 组件。由于部分可用区的开发机存在网络限制（无法访问公网），或者与 Microsoft 服务器连接不稳定，可能导致下载失败或极其缓慢。

下载 VS Code Server 要求 443 端口可访问以下域名：

• update.code.visualstudio.com
• vscode.download.prss.microsoft.com

如果您遇到 VS Code Server 下载失败或过慢的问题，可以采取以下方案。

方案一 强制本地下载 VS Code Server

此方案适用于以下两种情况：

1. 在远程主机上下载 Server 组件过慢
2. 在远程主机上下载 Server 组件失败

默认情况下，Remote - SSH 扩展会在远程主机下载 VS Code Server 失败后自动回退，先在本地下载 VS Code Server，并将其通过 scp 传输到远程主机。

1. 通过 remote.SSH.localServerDownload 设置来更改此行为，调整为 always，始终在本地下载后再传输。
2. 确保您本地机器可正常访问 VS Code Server 相关域名。
3. 由于传输过程依赖 scp，请确保您本地机器支持 scp 命令；请确保远程开发机镜像中已携带 openssh-server。详见镜像基础组件要求。
4. 如果 SSH 主机仅启用了密码认证（Password-based Authentication），在 scp 传输前 VS Code 将提示您再次输入 SSH 密码，如果未输入密码或密码错误，连接会直接失败。建议为开发机设置基于 SSH 密钥的认证。

完成以上步骤后，使用 VS Code Remote - SSH 扩展重试连接开发机。

注意

在开发机网络状况差、无法稳定下载 VS Code Server 时，也可以尝试修改 remote.SSH.localServerDownload 的方案。

方案二 手动传输和安装 VS Code Server

如果方案一仍无法解决问题，您需要在本地环境手动下载 VS Code Server，并传输到开发机中进行安装。

Step 0 获取 VSCode Commit ID

获取 VSCode Commit ID，以下两种方式可任选其一。

• 如果本地已安装 Code CLI，可直接获取 Commit ID。

  ~# code --version
  1.105.1
  7d842fb85a0275a4a8e4d7e040d2625abbf7f084
  arm64

  其中 7d842fb85a0275a4a8e4d7e040d2625abbf7f084 为 Commit ID。

• 打开本地的 VS Code 编辑器，点击「关于 Visual Studio Code」，在弹窗中复制"Commit ID/提交 ID"。

Step 1 在本地机器上下载离线安装包，并上传开发机

1. 在本地下载如下文件。

   commit_id=your_commit_id
   wget https://vscode.download.prss.microsoft.com/dbazure/download/stable/${commit_id}/vscode-server-linux-x64.tar.gz
   
   curl -Lk 'https://code.visualstudio.com/sha/download?build=stable&os=cli-alpine-x64' --output vscode_cli_alpine_x64_cli.tar.gz

2. 将下载的两个文件通过 scp 方式传到开发机上（请替换为自己的开发机 IP 和端口号）。

   scp -P 40350 vscode*.tar.gz root@122.228.252.26:/root/

Step 2 在开发机上安装离线安装包

1. 登录到开发机，解压上传的离线安装包。

   tar -zvxf vscode-server-linux-x64.tar.gz
   tar -zvxf vscode_cli_alpine_x64_cli.tar.gz

2. 解压后得到 1 个文件夹和 1 个文件，分别是 vscode-server-linux-x64 和 code，然后执行：

   commit_id=your_commit_id
   mkdir -p /root/.vscode-server/cli/servers/Stable-${commit_id}
   cp -r vscode-server-linux-x64 /root/.vscode-server/cli/servers/Stable-${commit_id}/server
   cp code /root/.vscode-server/code-${commit_id}

3. 完成以上步骤后，使用 VS Code Remote - SSH 扩展重试连接开发机。

手动安装 Cursor Server 端组件

在首次连接时，Cursor 会尝试在远程主机上下载 Server 组件。由于部分可用区的开发机存在网络限制（无法访问公网），或者与 Cursor 服务器连接不稳定，可能导致下载失败或极其缓慢。

如果您遇到 Cursor Server 下载失败或过慢的问题，特别是无法通过 Remote - SSH 扩展与开发机建立连接时，可以采取以下方案。

方案一 强制本地下载 Cursor Server

此方案适用于以下两种情况：

1. 在远程主机上下载 Server 组件过慢
2. 在远程主机上下载 Server 组件失败

默认情况下，Remote - SSH 扩展会在远程主机下载 Cursor Server 失败后自动回退，先在本地下载 Cursor Server，并将其通过 scp 传输到远程主机。

1. 通过 remote.SSH.localServerDownload 设置来更改此行为，调整为 always，始终在本地下载后再传输。
2. 确保您本地机器可正常访问 VSCode Server 相关域名。
3. 由于传输过程依赖 scp，请确保您本地机器支持 scp 命令；请确保远程开发机镜像中已携带 openssh-server。详见镜像基础组件要求。
4. 如果 SSH 主机仅启用了密码认证（Password-based Authentication），在 scp 传输前 Cursor 将提示您再次输入 SSH 密码，如果未输入密码或密码错误，连接会直接失败。建议为开发机设置基于 SSH 密钥的认证。

完成以上步骤后，使用 Cursor 通过 Remote - SSH 重试连接开发机。

注意

在开发机网络状况差、无法稳定下载 Cursor Server 时，也可以尝试修改 remote.SSH.localServerDownload 的方案。

方案二 手动传输和安装 Cursor Server

如果方案一仍无法解决问题，您需要在本地环境手动下载 Cursor Server，并传输到开发机中进行安装。

Step 0 获取 Cursor Commit ID

获取 VSCode Commit ID，以下两种方式可任选其一。

• 如果本地已安装 Cursor CLI，可直接获取 Commit ID。

  ~# cursor --version
  2.0.43
  8e4da76ad196925accaa169efcae28c45454cce0
  arm64

  其中 8e4da76ad196925accaa169efcae28c45454cce0 为 Commit ID。

• 打开本地的 Cursor 编辑器，点击「关于 Cursor」，记录弹窗中的版本号和提交 ID。

Step 1 在本地机器上下载离线安装包，并上传开发机

1. 在本地下载如下文件。

   cursor_version=2.0.43
   commit_id=8e4da76ad196925accaa169efcae28c45454cce0
   wget https://cursor.blob.core.windows.net/remote-releases/${cursor_version}-${commit_id}/vscode-reh-linux-x64.tar.gz

2. 将下载的文件通过 scp 方式传到开发机上（请替换为自己的开发机 IP 和端口号）。

   scp -P 40350 vscode-reh-linux-x64.tar.gz root@122.228.252.26:/root/

Step 2 在开发机上安装离线安装包

1. 登录到开发机，解压并安装上传的离线安装包。

   commit_id=8e4da76ad196925accaa169efcae28c45454cce0
   mkdir -p ~/.cursor-server/bin/${commit_id}
   tar xvzf vscode-reh-linux-x64.tar.gz
   cp -r ~/vscode-reh-linux-x64/* ~/.cursor-server/bin/${commit_id}/

2. 完成以上步骤后，使用 Cursor 通过 Remote - SSH 重试连接开发机。