【深度学习项目实战·04】VS Code远程开发：在本地编辑，在服务器运行与调试

文章目录

• • [01 本篇要解决什么问题](#01 本篇要解决什么问题)
  • [02 背景：界面在本地，哪些东西在远程？](#02 背景：界面在本地，哪些东西在远程？)
  • [03 实操：连接、选环境、调试与查看服务](#03 实操：连接、选环境、调试与查看服务)
  • • （1）先确认命令行SSH已经能用
    • （2）给服务器配置一个SSH别名
    • （3）连接远程窗口，打开项目文件夹
    • （4）在远程安装Python扩展并选择远程解释器
    • （5）用固定启动配置做断点调试
    • （6）通过端口转发查看远程服务
    • （7）正式长训练与交互调试分开管理
  • [04 一个具体例子：解释"终端能跑，F5却找不到包"](#04 一个具体例子：解释“终端能跑，F5却找不到包”)
  • [05 常见问题与自测](#05 常见问题与自测)
  • [06 本篇回顾与下一步](#06 本篇回顾与下一步)

01 本篇要解决什么问题

服务器环境已经装好，但开发时还在本地改文件、手动上传、远程执行之间来回切换，很容易出现"改的不是运行的那份代码"。

Remote-SSH可以让本地VS Code直接打开远程项目，并在服务器上运行终端、解释器和调试器。本篇用前面的小训练完成一次远程编辑与断点调试。

• 本篇关键词：Remote-SSH、远程窗口、解释器、debugpy、工作目录、端口转发。
• 完成标志：知道文件、Python、训练进程分别在哪里，能在远程代码中停住断点并检查张量。
• 一句话概括：远程开发把界面放在本地，把代码执行与项目环境放在服务器，连接后仍需选对远程解释器。

02 背景：界面在本地，哪些东西在远程？

Remote-SSH连接后，VS Code会在远程启动相应组件，打开远程文件。Python相关扩展可在远程扩展宿主运行，实际使用远程Python环境。

对象	所在位置
编辑器界面和键盘输入	本地电脑
打开的项目文件	远程服务器
远程集成终端、Python与训练	远程服务器
远程Python依赖	远程选中的环境
转发服务的浏览器访问入口	本地端口，连接到远程服务

本地安装了某个Python包，不会自动让远程解释器拥有它。连接关系与组件位置可核对Remote-SSH官方说明。

03 实操：连接、选环境、调试与查看服务

（1）先确认命令行SSH已经能用

使用第02篇的实际账号与地址完成SSH登录。若命令行都无法连接，先处理网络、端口和认证，不要把所有错误归因于VS Code扩展。

在本地VS Code安装Microsoft的Remote - SSH扩展。远程Linux还需要满足当前VS Code Server的系统库要求，按Linux前置条件核对；旧发行版不能只因为SSH可登录，就认定远程组件一定兼容。

（2）给服务器配置一个SSH别名

打开本地用户的SSH配置文件，添加以下内容。Windows通常位于用户目录下的.ssh/config，也可以通过Remote-SSH的配置命令选择：

Host dl-server
    HostName 203.0.113.10
    User your_name
    Port 22
    ServerAliveInterval 30
    ServerAliveCountMax 3

将文档示例地址、用户名和端口换成实际值。Host是本地别名；HostName才是真实目标地址。若已有密钥认证，可增加指向本地专用私钥的IdentityFile，不要把私钥复制到项目或服务器作为配置步骤。

验证别名：

ssh dl-server

保活参数可以帮助维持连接或及时发现断连，但不保证网络永不断开，也不承担训练状态恢复。

（3）连接远程窗口，打开项目文件夹

执行Remote-SSH: Connect to Host...，选择dl-server。连接成功后，通过窗口中的远程连接标识确认目标，再打开服务器上的~/dl-course-lab实际目录。

新建集成终端，执行：

hostname
pwd

应当得到远程主机名与远程项目路径。这里打开的不是本地同名文件夹；后续编辑保存会作用于远程文件。

（4）在远程安装Python扩展并选择远程解释器

按扩展界面的提示，将Python与Python Debugger扩展安装到远程环境。然后执行Python: Select Interpreter，选择服务器dl-course对应的Python。

远程终端可能还需要加载已有Conda：

source "$HOME/miniconda3/etc/profile.d/conda.sh"
conda activate dl-course
python -c "import sys; print(sys.executable)"

上述Conda位置按第02篇个人安装示例给出；使用平台Conda时替换为平台的加载方式。终端激活与编辑器选解释器需要分别确认。

先运行：

python examples/smoke_train.py --device cpu --output artifacts/remote_cpu

有已分配GPU、并完成第03篇验证后，再切换到CUDA。若平台要求计算节点，按其远程开发或任务调试流程进入正确节点，不能仅因为远程窗口已连接就直接使用登录节点训练。

（5）用固定启动配置做断点调试

在远程项目创建.vscode/launch.json，配套包也提供了同样的模板：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "DL course: CPU smoke",
      "type": "debugpy",
      "request": "launch",
      "program": "${workspaceFolder}/examples/smoke_train.py",
      "args": ["--device", "cpu", "--output", "${workspaceFolder}/artifacts/debug_smoke"],
      "cwd": "${workspaceFolder}",
      "console": "integratedTerminal",
      "justMyCode": true
    }
  ]
}

这个配置使用选中的解释器，固定项目根目录作为cwd，并把输出写到单独位置。type使用当前Python调试器对应的debugpy，具体字段可参考官方调试说明。

打开smoke_train.py，在计算loss的位置设置断点，再从"运行和调试"选择该配置。停住后检查：

x.shape
x.device
next(model.parameters()).device
loss.item()

刚进入循环、尚未计算loss时它可能不存在，因此要把断点放在合适行。断点调试会改变执行节奏，不适合拿来直接衡量正常训练速度。

（6）通过端口转发查看远程服务

以可选TensorBoard为例，先在远程环境安装并启动：

python -m pip install tensorboard
python -m tensorboard.main --logdir artifacts --host 127.0.0.1 --port 6006

再用VS Code的端口面板转发6006，访问面板显示的本地地址。也可以在本地另开终端：

ssh -L 16006:127.0.0.1:6006 dl-server

保持该连接，从本地浏览器访问http://127.0.0.1:16006。远程6006与本地16006承担不同角色。

本部分小训练保存JSON而非TensorBoard事件，所以面板可能没有曲线；后续实验记录章节会加入事件写入。端口转发负责连接服务，不会自动生成训练日志。

（7）正式长训练与交互调试分开管理

断点调试用于定位问题。长时间训练应按服务器规则使用调度作业或适当的会话管理，并保留日志、配置和检查点。

关闭VS Code窗口不应当作为训练状态管理办法，也不能假定调试进程一定会继续运行。第02篇的任务运行约定仍然适用。

图：本地界面连接远程项目和解释器；端口转发把本地访问映射到远程服务，与Python环境选择是两条不同链路。

04 一个具体例子：解释"终端能跑，F5却找不到包"

先在远程终端打印：

python -c "import sys; print(sys.executable)"

再在F5调试过程中检查sys.executable。如果一个属于dl-course，另一个属于系统Python，问题就定位到解释器选择，而非服务器一定没安装依赖。

若解释器相同，再检查cwd、参数、环境变量及模块搜索路径。采用上面的固定启动配置，可减少"从不同目录启动同一文件"带来的差异。

05 常见问题与自测

问题1：本地装好Python包，远程为什么还提示缺失？

两个解释器环境相互独立，需要在远程实际使用的环境安装依赖。

问题2：SSH成功，Remote-SSH仍失败，应该检查什么？

查看Remote-SSH输出日志，继续区分远程组件系统要求、网络下载、磁盘与启动问题。

问题3：终端已经激活环境，还要选择解释器吗？

需要确认。调试器和编辑器的解释器选择，不应只从某个已有终端的提示符推断。

问题4：为什么断点旁边显示没有绑定？

可能启动了另一份文件、路径不匹配、代码尚未加载，或调试目标不正确。先确认实际执行的程序与文件路径。

问题5：转发端口后没有曲线，是连接失败吗？

不一定。先区分服务是否可访问，再检查对应目录中是否真的写入了该工具能读取的日志。

06 本篇回顾与下一步

一次可靠远程调试，需要对齐主机、文件、解释器、工作目录和启动参数。状态栏提供连接提示，真正的运行证据来自程序和终端输出。

中文	常用英文
远程扩展宿主	Remote extension host
解释器选择	Interpreter selection
启动配置	Launch configuration
断点／调用栈	Breakpoint / Call stack
端口转发	Port forwarding

下一篇整理常见环境问题，把报错按层定位，并保存足够的复现信息。

参考与延伸阅读

• VS Code Remote-SSH。
• 远程Linux前置条件。
• Python解释器与环境。
• Python调试配置。