三亩地 三亩地SAN MU DI · CODE DIARY
交流投稿
ARTICLE DETAIL

日记详情

真实记录编程学习的某一天，欢迎挑你感兴趣的翻一翻。

首页/学习日记/日记详情

VS Code远程连接Jupyter服务器：无缝融合本地开发与远程计算

发布时间：2026/8/16 19:49:49 三亩地 编程学习日记
VS Code远程连接Jupyter服务器：无缝融合本地开发与远程计算

1. 项目概述：为什么我们需要远程Jupyter？

作为一名经常和数据、模型打交道的开发者，我猜你也遇到过这样的困境：本地电脑性能孱弱，跑个稍大的数据集或者训练一个深度学习模型，风扇就狂转不止，CPU/GPU占用率拉满，电脑烫得能煎鸡蛋，而手头明明有一台性能强劲的远程服务器（可能是实验室的、公司的，或者是云服务商租的），却只能通过笨拙的命令行操作，调试和可视化体验极差。

传统的做法是，在远程服务器上启动Jupyter Notebook或Lab服务，然后在本地浏览器中通过http://服务器IP:8888来访问。这个方法简单直接，但问题一大堆：首先你得配置SSH隧道做端口转发，命令一长串容易记错；其次，浏览器标签页一多，代码编辑体验远不如专业的IDE；最重要的是，文件管理非常割裂——编辑器的文件树和Jupyter服务器上的文件是两套体系，上传下载文件得靠scp或者拖拽，效率低下。

所以，今天要聊的这个“一下午终于配好”的场景，其核心价值就在于：将强大的远程计算资源与本地VS Code的极致开发体验无缝融合。你可以在VS Code里直接打开远程服务器上的Jupyter Notebook（.ipynb文件），享受代码补全、语法高亮、集成终端、源码管理（Git）等全套IDE功能，同时代码实际是在远程服务器上执行的，结果和文件也直接保存在服务器上。这不仅仅是连接，更是一种开发范式的升级，让你能像操作本地文件一样，流畅地操作远程计算环境。

2. 核心思路与工具选型解析

要实现这个目标，我们需要一个“桥梁”来连接本地的VS Code和远程的Jupyter内核。经过一番折腾和对比，目前最主流、最稳定的方案是VS Code Remote - SSH 扩展 + Python扩展的远程Jupyter服务器支持。这个组合拳能完美解决上述痛点。

2.1 为什么是Remote-SSH + Python扩展？

首先，VS Code Remote - SSH扩展是整个方案的基石。它允许你将VS Code的整个“后端”（包括扩展、终端、文件读写）都运行在远程服务器上，而本地只运行一个轻量级的“前端”UI。这样，VS Code中的所有操作（比如打开文件、运行终端命令、安装扩展）都像是在远程服务器上直接进行。这为我们访问远程文件系统提供了原生级别的支持。

其次，Python扩展是执行Jupyter的核心。当你在远程环境中安装了Python扩展后，它就能识别远程服务器上的Python解释器和Jupyter环境。其关键功能在于，它可以配置一个“Jupyter服务器连接信息”，指向远程服务器上运行的Jupyter内核。这样，当你打开一个.ipynb文件时，Python扩展就会自动使用这个远程内核来执行代码单元，而不是试图在本地启动一个内核。

为什么不直接用Jupyter的远程访问功能？正如开头所说，浏览器访问体验差，且与本地开发环境割裂。为什么不直接用PyCharm Professional？PyCharm专业版确实有强大的远程开发功能，但它是付费的。VS Code这套方案完全免费，且对于已经熟悉VS Code生态的开发者来说，迁移成本几乎为零。

2.2 方案架构与数据流

理解数据流有助于排查问题。整个架构可以简化为三层：

  1. 本地VS Code UI层：你看到的界面，接收键盘鼠标输入，渲染代码和图表。
  2. Remote-SSH 通信层：通过SSH协议，安全地将UI层的操作指令（如“运行这个Cell”）传递到远程服务器，并将远程服务器的输出（如代码结果、错误信息、图表图像）传回本地显示。
  3. 远程服务器执行层：
    • VS Code Server：由Remote-SSH扩展自动安装在远程机器上的轻量级服务，负责协调。
    • Python解释器 & Jupyter内核：实际执行代码的“大脑”。
    • Jupyter服务器（Notebook/Lab）：作为内核管理器。VS Code的Python扩展会与这个服务器通信，请求启动内核并与之交互。

当你点击运行一个Cell时，指令流是：本地UI -> SSH隧道 -> 远程VS Code Server -> Python扩展 -> Jupyter服务器 -> 指定的Jupyter内核 -> 执行代码 -> 结果沿原路返回显示在你的VS Code中。图表等输出会被序列化后通过SSH传回，在你的本地界面中渲染出来。

3. 详细配置步骤与实操要点

接下来，我们一步步拆解配置过程。我把自己踩过的坑和关键注意事项都揉在里面了，请务必仔细阅读每一步的说明。

3.1 前期准备：远程服务器端检查清单

在本地动手之前，请先通过SSH终端连接到你的远程服务器，完成以下检查。很多连接失败的问题，根源都在于服务器端配置不全。

  1. Python与Jupyter环境：确保服务器上已安装了你需要的Python版本（如Anaconda或Miniconda环境）。然后安装Jupyter：

    # 如果使用conda环境，请先激活 # conda activate your_env_name pip install jupyter notebook jupyterlab

    注意：最好在项目所需的虚拟环境中安装，避免包冲突。记下你的Python解释器路径，例如~/miniconda3/envs/myproject/bin/python。

  2. 测试Jupyter能否本地启动：

    # 临时启动一个Notebook服务器，指定IP和端口 jupyter notebook --ip=0.0.0.0 --port=8889 --no-browser

    如果看到输出中包含http://[服务器IP]:8889/?token=...的链接，说明Jupyter服务本身正常。按Ctrl+C停止它。

  3. 防火墙与安全组：虽然我们最终通过SSH隧道通信（不需要对公网开放Jupyter端口），但确保服务器SSH端口（默认22）可访问是前提。如果是云服务器，请检查安全组规则是否允许你的本地IP访问22端口。

3.2 本地VS Code环境配置

  1. 安装必要扩展：

    • 在VS Code扩展商店搜索并安装“Remote - SSH”（微软官方发布）。
    • 搜索并安装“Python”（微软官方发布）。这个扩展也包含了Jupyter的核心支持。

  2. 配置Remote-SSH连接：

    • 点击VS Code左侧活动栏的“远程资源管理器”图标（或按F1输入Remote-SSH: Connect to Host...）。
    • 选择“配置SSH Hosts...”，然后编辑你的~/.ssh/config文件（Windows通常在C:\Users\你的用户名\.ssh\config）。
    • 添加服务器配置，一个完整的配置示例：
      Host my-remote-server # 给你的服务器起个别名 HostName 123.123.123.123 # 服务器的公网IP或域名 User your_username # 登录用户名 Port 22 # SSH端口，默认22，如果改了请填写修改后的端口 IdentityFile ~/.ssh/id_rsa # 私钥路径，如果使用密钥登录（推荐） # 如果是密码登录，则不需要IdentityFile这一行
    • 保存后，在远程资源管理器中就能看到my-remote-server这个主机了。

3.3 连接远程主机并配置Python环境

  1. 首次连接：点击my-remote-server旁边的连接按钮。VS Code会打开一个新窗口，状态栏显示“正在连接到 SSH: my-remote-server...”。首次连接会自动在远程服务器上安装 VS Code Server，这需要一些时间，取决于网络速度。
  2. 安装Python扩展的远程实例：连接成功后，你实际上已经在一个“远程窗口”中工作了。点击扩展图标，你会发现“Remote - SSH”扩展显示为“已在本地安装”，而“Python”扩展显示为“可在 SSH: my-remote-server 上安装”。点击“在 SSH: ... 上安装”按钮。这一步至关重要！这会把Python扩展的功能部署到远程服务器上。
  3. 选择远程Python解释器：安装完成后，打开一个文件夹（比如你的项目目录/home/your_username/project）。然后按Ctrl+Shift+P打开命令面板，输入Python: Select Interpreter，选择远程服务器上你准备好的Python环境路径（就是之前记下的那个，如~/miniconda3/envs/myproject/bin/python）。VS Code右下角状态栏会显示当前选择的解释器。

3.4 配置并连接远程Jupyter服务器

这是最核心也最容易出错的一步。

  1. 在远程服务器上启动Jupyter：在VS Code的远程窗口中，打开一个集成终端（Ctrl+`）。这个终端实际上是在远程服务器上运行的。在其中启动Jupyter Lab或Notebook。强烈建议指定一个固定的、不常用的端口，并允许所有IP连接，但不需要浏览器：

    # 启动Jupyter Lab jupyter lab --ip=0.0.0.0 --port=8889 --no-browser --NotebookApp.token='' --NotebookApp.password='' # 或者启动Jupyter Notebook # jupyter notebook --ip=0.0.0.0 --port=8889 --no-browser --NotebookApp.token='' --NotebookApp.password=''
    • --ip=0.0.0.0：允许任何IP连接（因为VS Code扩展会从内部连接）。
    • --port=8889：指定端口，避免与服务器上其他服务冲突。
    • --no-browser：不自动打开浏览器。
    • --NotebookApp.token=''和--NotebookApp.password=''：将认证置空。注意：这仅在SSH保护的远程开发环境中是安全的，因为外部无法直接访问这个端口。如果你直接在公网服务器上这样启动Jupyter而不加SSH保护，是极度危险的！我们的场景下，连接是通过VS Code Remote-SSH建立的，本身已有SSH加密和认证，所以可以简化Jupyter的认证。

  2. 获取连接信息：启动命令会输出一串信息，其中最关键的一行是：

    http://localhost:8889/?token=... 或者 http://127.0.0.1:8889/?token=...

    复制这个http://localhost:8889部分（或者http://127.0.0.1:8889）。注意，这里一定是localhost或127.0.0.1，而不是服务器的公网IP。因为对于已经通过SSH连接到服务器的VS Code Server进程来说，Jupyter服务就运行在它的“本地”。

  3. 在VS Code中配置Jupyter服务器：

    • 在远程窗口，按Ctrl+Shift+P打开命令面板。
    • 输入Jupyter: Specify local or remote Jupyter server for connections并选择。
    • 选择“现有”选项。
    • 在弹出的输入框中，粘贴上一步复制的URI，即http://localhost:8889。然后回车。
    • 如果配置成功，VS Code右下角会出现提示“Jupyter服务器：已连接至 http://localhost:8889”。

3.5 创建或打开Notebook并验证

  1. 在VS Code远程窗口的资源管理器中，右键点击，选择“新建文件”，命名为test.ipynb。
  2. 文件创建后，VS Code会自动将其识别为Jupyter Notebook，界面会变成熟悉的Cell模式。
  3. 在第一个Cell中输入简单的测试代码，例如：
    import sys print(sys.executable) import numpy as np np.random.rand(3, 3)
  4. 点击Cell左侧的“运行”按钮。稍等片刻，你应该能看到输出。sys.executable打印的路径应该就是你之前选择的远程Python解释器路径，而numpy矩阵也能正常计算和显示。

至此，大功告成！你现在可以在VS Code里享受完整的编辑、调试体验，同时所有计算都在远程服务器上执行。你可以打开服务器上的任何.ipynb文件进行编辑，新建的文件也会直接保存在服务器上。

4. 常见问题、排查技巧与深度优化

配置过程很少一帆风顺，下面是我在多次配置中总结的“踩坑实录”和解决方案。

4.1 连接失败经典错误与排查

错误现象可能原因排查步骤与解决方案
VS Code提示“无法连接到Jupyter服务器”1. Jupyter服务未启动或已崩溃。
2. 端口被占用。
3. VS Code中配置的URI错误。		1. 回到远程终端，检查Jupyter进程是否在运行 (`ps aux
运行Cell长时间无响应或超时1. 远程服务器内核启动慢或卡死。
2. 网络延迟高或SSH连接不稳定。
3. 缺少某些依赖包。		1. 在远程终端尝试用jupyter console手动连接内核，看是否正常。
2. 优化SSH连接：在~/.ssh/config中添加ServerAliveInterval 60和ServerAliveCountMax 3保持连接活跃。
3. 在Cell中先运行!pip list检查关键包是否已安装。
无法显示图表（Matplotlib等）远程Jupyter内核没有图形后端，或VS Code交互模式未正确配置。1. 在代码中强制指定非交互式后端并保存为图片：
python<br> import matplotlib<br> matplotlib.use('Agg') # 在导入pyplot之前设置<br> import matplotlib.pyplot as plt<br> plt.plot([1,2,3])<br> plt.savefig('plot.png')<br> from IPython.display import Image<br> Image(filename='plot.png')<br>
2. 更推荐的方式：安装ipympl以支持交互式图表。
bash<br> pip install ipympl<br>
然后在Cell开头使用魔法命令：
<br> %matplotlib widget<br>
这能在VS Code内渲染出可交互的图表。
VS Code无法识别.ipynb文件Python扩展的Jupyter功能未正确加载或版本不兼容。1. 确认在远程窗口安装了Python扩展。
2. 检查VS Code和Python扩展是否为最新版。
3. 在命令面板运行Developer: Reload Window重载窗口。

4.2 提升体验的进阶配置

  1. 自动化脚本：每次手动启动Jupyter服务很麻烦。可以在服务器上写一个简单的启动脚本start_jupyter.sh：

    #!/bin/bash # 激活conda环境 source ~/miniconda3/bin/activate your_env_name # 启动jupyter lab，并将日志输出到文件 nohup jupyter lab --ip=0.0.0.0 --port=8889 --no-browser --NotebookApp.token='' --NotebookApp.password='' > ~/jupyter.log 2>&1 & echo “Jupyter Lab started on port 8889. PID: $!”

    赋予执行权限chmod +x start_jupyter.sh。以后只需运行./start_jupyter.sh。关闭则用pkill -f jupyter。

  2. 配置多个Jupyter服务器：如果你有多个项目或环境，可以在VS Code中配置多个服务器。通过命令面板Jupyter: Specify Jupyter server选择不同的URI即可快速切换。甚至可以在工作区设置.vscode/settings.json里为特定项目指定：

    { “jupyter.jupyterServerType”: “remote”, “jupyter.remoteJupyterServer”: [“http://localhost:8889”] }

  3. 使用密钥对免密登录SSH：避免每次输入密码。在本地生成密钥对ssh-keygen -t rsa，将公钥id_rsa.pub的内容追加到远程服务器的~/.ssh/authorized_keys文件中。然后在VS Code的SSH配置里指定IdentityFile路径。

4.3 安全注意事项重申

虽然我们为了方便关闭了Jupyter的token认证，但这个方案的安全性完全建立在SSH连接的安全性之上。务必确保：

  • 远程服务器的SSH服务保持最新，使用强密码或密钥对。
  • 避免在公网服务器上使用弱SSH密码。
  • 如果服务器有公网IP，考虑将SSH端口从默认的22改为其他端口，并配置防火墙只允许可信IP访问。
  • 绝对不要将带有--NotebookApp.token=''参数的Jupyter服务直接暴露在公网（即绑定到公网IP且防火墙开放了对应端口）。

5. 个人实操心得与最终建议

折腾一下午配好的经历，让我对这套工作流的细节有了更深的体会。首先，耐心阅读错误信息是关键。VS Code的输出面板和Jupyter服务器的日志（启动时在终端输出的信息，或者我们重定向到jupyter.log文件的信息）包含了绝大部分问题的答案，很多错误码直接搜索就能找到解决方案。

其次，环境隔离是救星。强烈建议为每个项目创建独立的conda或venv虚拟环境，并在该环境中安装Jupyter。这能彻底避免包版本冲突，也让服务器环境保持整洁。在VS Code中选择解释器时，直接指向虚拟环境下的python即可。

关于Jupyter Notebook和Lab的选择，我个人更倾向于Jupyter Lab。它在远程VS Code中的兼容性似乎更好，而且其模块化界面理念与VS Code本身更契合。不过，两者在核心的代码执行功能上没有区别。

最后，这套组合拳一旦打通，生产力提升是巨大的。你获得了一个集成的、强大的、可远程计算的开发环境。你可以用VS Code的Git管理代码，用终端操作服务器文件，用调试器调试Notebook，所有操作无缝衔接。对于数据科学、机器学习或任何需要交互式编程和重型计算的任务，这几乎是目前最优雅的解决方案之一。如果遇到问题，不要灰心，按照上述排查步骤一步步来，你一定能享受到这种流畅的远程编程体验。

编程学习 学习日记 实战经验
← 返回列表