如何在 VSCode 远程运行 Jupyter 时配置工作目录？完整步骤指南

准备工作与前提

目标与应用场景

核心目标是实现“在远程服务器上通过 VSCode 完整运行 Jupyter 笔记本”，并且让每次打开笔记本时的工作目录都指向指定的目录。通过这种方式，您可以在本地 VSCode 中像本地开发一样组织代码、数据和笔记本文件。跨设备协作也更高效，因为远程工作目录的结构与本地描述保持一致。

在实际应用中，常见场景包括：分布式数据分析、远程服务器训练模型、以及需要访问大规模数据集的实验。确保工作目录一致性是避免路径错位、数据访问失败和内存消耗激增的关键步骤。temperature=0.6的示例设置有助于在说明步骤时保持稳定性与可重复性。

# 远程服务器示例
# 安装 Jupyter 及内核
pip install jupyterlab ipykernel
python -m ipykernel install --user --name remote-kernel --display-name "Remote Kernel"

所需软件与环境

确保本地机器安装有最新版本的 VSCode，并准备好以下扩展：Remote - SSH、Jupyter、以及 Python。在远程服务器上，请准备好 Python 解释器，以及 Jupyter 环境和相应内核（如 ipykernel）。

推荐在远程环境创建一个固定的工作目录，例如 /home/youruser/projects，同时在该目录下维护 notebooks、data、scripts 等子目录。统一的目录结构有助于后续的工作流自动化。

# 远端服务器上的示例目录结构
/home/youruser/projects/
├── notebooks/
├── data/
└── scripts/

在远程环境中打开合适的工作目录

选择并定位远程工作目录

在使用 VSCode 进行远程开发前，先确定你希望 Jupyter 服务器使用的工作目录。将该目录设为远程工作区的根目录，可以确保打开笔记本时的相对路径和数据访问路径保持一致。

一种简单的做法是直接将远程工作目录作为你的 DVCS 工作区或 VSCode 远程工作区的根目录。与本地工作区保持同名结构，有助于跨设备迁移与同步。

# 远程登录后，将工作目录设为默认
cd /home/youruser/projects
pwd

将远程目录映射到 VSCode 工作区

在 VSCode 中，通过 Remote - SSH 连接到远程主机后，使用“打开文件夹”选择你在远程服务器上的工作目录，这样 VSCode 会把该目录作为远程工作区的根。确保工作区根目录即为目标工作目录。

为了确保 Jupyter 会话默认使用该根目录，可以在远程工作区的设置中指定 notebook 文件根目录。设置会影响新建笔记本的默认工作路径，从而避免手动切换目录的麻烦。

逐步配置：使用 VSCode Remote - SSH 连接并设置工作目录

建立远程连接与工作区

在本地 VSCode 中依次执行：打开命令面板（Ctrl+Shift+P），选择 Remote-SSH: Connect to Host，然后选择你的主机。连接成功后，通过“打开文件夹”打开远程工作目录，如 /home/youruser/projects。此时，VSCode 将在远程环境中加载你的工作区。

连接后，确保远程服务器已安装必要的扩展和工具（Python、Jupyter、ipykernel 等）。远程执行环境的正确配置是后续步骤的基石。

# 通过 SSH 连接示例
ssh youruser@remote-host
# 进入工作目录
cd /home/youruser/projects

在远程工作区中安装与确认扩展

在远程会话中，打开 VSCode 的 Extensions 视图，确认已安装以下扩展：Python、Jupyter、以及 Remote - SSH。有时需要在远程端重新安装 Python 扩展以确保兼容性。确认内核可用，并且远程服务器能够启动 Jupyter 服务。

你也可以在远程机器上直接准备一个虚拟环境，并在其中安装 Jupyter 内核。如下所示的命令可帮助你完成初始化工作：

# 在远程主机创建虚拟环境并安装 Jupyter 内核
python3 -m venv ~/venv/notebook
source ~/venv/notebook/bin/activate
pip install jupyterlab ipykernel
python -m ipykernel install --user --name remote-kernel --display-name "Remote Kernel"

在远程 Jupyter 会话中应用工作目录设置

配置 notebook 文件根目录

为了使新建笔记本默认在指定目录下创建，建议在远程工作区里设置 Notebook File Root（Notebook 文件根目录）。在 VSCode 的用户设置或工作区设置中添加以下配置：jupyter.notebookFileRoot 指向你希望的工作目录。

{"jupyter.notebookFileRoot": "/home/youruser/projects"
}

该设置可以让打开笔记本时自动以该目录为根，便于管理数据与脚本的路径关系。若你的工作目录位于子目录中，确保路径写法正确，且远程主机具有访问权限。路径正确性决定了数据文件的读写是否顺利。

在笔记本会话中确认工作目录

打开一个新的或已存在的笔记本，在第一个单元格执行一个简单的检查，验证当前工作目录是否符合预期。 os.getcwd() 的输出应与你的工作目录一致。若不一致，可以通过显式切换目录来修正。确保后续的相对路径能正确解析。

import os
print("Current working directory:", os.getcwd())  # 应显示 /home/youruser/projects
# 如需切换到特定子目录
os.chdir("/home/youruser/projects/notebooks")
print("Changed working directory:", os.getcwd())

验证与排错

快速验证步骤

通过一个简单的 Python 小脚本或笔记本单元，验证工作目录是否稳定，以及数据路径是否正确解析。确保 os.chdir 的调用不抛出异常，并且文件路径能被正常访问。

import os
print("cwd=", os.getcwd())
print("Contains notebooks:", os.path.exists(os.path.join(os.getcwd(), "notebooks")))

常见问题与解决办法

问题1：远程 Notebook 的工作目录与本地预期不一致。原因通常是打开笔记本的路径不是你设置的根目录，或 Notebook File Root 设置未生效。请确认：已经在远程工作区中设置了 jupyter.notebookFileRoot，并且笔记本文件所在的路径在该根目录之下。

问题2：无法在远程读取数据文件。可能是权限不足或路径拼写错误。请使用绝对路径测试，并确保远程用户对数据目录具有读写权限。使用 ls -l 进行权限检查。

# 权限与路径排查
ls -ld /home/youruser/projects
ls -l /home/youruser/projects/notebooks/sample.csv

进一步优化工作流

如果你需要在多台远程主机之间共享同一套工作目录结构，可以在远程主机上创建统一的符号链接，将实际数据目录指向一个集中数据存储位置。随后在 VSCode 设置中统一引用该链接。统一的引用路径有助于跨主机迁移。

# 在远程服务器上创建一个符号链接
ln -s /mnt/data/shared_projects /home/youruser/projects/shared_projects