1. 问题背景与挑战
当我们在VSCode中通过SSH连接到远程服务器并使用远程Jupyter内核时，Jupyter会话的默认工作目录通常是启动Jupyter服务器的根目录（例如/home/foouser/src/）。这意味着，即使您打开的是位于项目子目录（如/home/foouser/src/project2/main.ipynb）中的Notebook文件，其执行环境的工作目录仍然是Jupyter服务器的启动目录。
这种默认行为会导致一个常见的问题：相对路径导入失败。例如，在/home/foouser/src/project2/main.ipynb中尝试导入同项目下的library/resource.py时，如果直接使用from library import resource，就会抛出ModuleNotFoundError。这是因为Jupyter内核的工作目录并非project2，而是其父目录。
考虑以下项目结构：
.
└── /home/foouser/src/
├── project1/
│ └── main.ipynb
├── project2/
│ ├── library/
│ │ └── resource.py
│ └── main.ipynb
└── project3/
├── ham/
│ └── spam.py
└── main.ipynb如果您在/home/foouser/src/project3/main.ipynb中执行from ham import spam，当Jupyter服务器在/home/foouser/src/启动时，您会遇到ModuleNotFoundError。
2. 无效的尝试与局限性
在解决此问题时，一些常见的尝试往往效果不佳或存在局限性：
- 在每个项目目录启动独立的Jupyter实例： 这种方法虽然可以解决特定项目的相对导入问题，但需要在不同项目之间频繁切换Jupyter实例，效率低下且对远程服务器资源消耗较大，尤其对于资源有限的设备（如树莓派）而言。
- 设置"jupyter.notebookFileRoot": "${fileDirname}"： 这个VSCode设置看起来很有希望，但经过验证，它仅适用于本地Jupyter实例，对远程内核无效。这是因为该变量在远程连接场景下无法正确解析。
- 在Notebook中手动切换目录： 尝试在Notebook的第一个单元格中编写Python代码来动态获取当前文件路径并切换工作目录（例如使用os.chdir(os.path.dirname(os.path.realpath(__file__)))），这种方法虽然可以实现，但不够优雅，需要每个Notebook都包含相同的样板代码，且可能存在兼容性问题。
3. 解决方案：利用jupyter.runStartupCommands
VSCode Jupyter扩展提供了一个强大的配置项jupyter.runStartupCommands，它允许用户在Jupyter内核启动时执行一系列命令。通过巧妙利用这个特性，我们可以在内核初始化时自动将工作目录切换到当前打开的Notebook文件所在的目录。
核心原理： VSCode Jupyter扩展在启动远程内核时，会提供一个内部变量__vsc_ipynb_file__，它包含了当前Notebook文件的完整路径。我们可以利用这个变量来动态地获取Notebook所在的目录，并使用Jupyter的魔术命令%cd来切换工作目录。
配置步骤：
打开VSCode的设置（Ctrl+, 或 Cmd+,）。
搜索“Jupyter”或直接编辑您的settings.json文件。您可以通过点击右上角的 {} 图标进入settings.json。
-
在settings.json中添加或修改以下配置：
{ "jupyter.runStartupCommands": [ "import os", "__t=os.path.dirname(__vsc_ipynb_file__)", "%cd {__t}", "del __t" ] }
代码解析：
- "import os": 导入Python的os模块，用于路径操作。
- "__t=os.path.dirname(__vsc_ipynb_file__)":
- __vsc_ipynb_file__：这是VSCode Jupyter扩展在内核启动时提供的一个内部变量，其值为当前正在运行的Notebook文件的完整路径（包括文件名）。
- os.path.dirname(...)：Python os模块的函数，用于获取给定路径的目录部分。
- 这行代码的作用是将当前Notebook文件所在的目录路径赋值给一个临时变量__t。
- "%cd {__t}":
- %cd：这是Jupyter的魔术命令，用于切换当前会话的工作目录。
- {__t}：将之前获取到的Notebook目录路径插入到%cd命令中。
- 这行代码实现了将Jupyter内核的工作目录切换到当前Notebook文件所在的目录。
- "del __t": 删除临时变量__t，保持环境整洁。
4. 效果与注意事项
配置完成后，每次您在VSCode中打开一个远程Jupyter Notebook并连接到远程内核时，上述命令都会自动执行。这意味着您的Notebook的执行环境的工作目录将始终是其自身所在的目录，从而确保所有相对导入（如from library import resource）都能正常工作，解决了ModuleNotFoundError的问题。
注意事项：
- 全局或工作区设置： 您可以将此配置添加到用户settings.json（全局生效）或工作区settings.json（仅对当前工作区生效）。对于需要特定远程环境的项目，建议使用工作区设置。
- 内核重启： 修改settings.json后，您可能需要重启Jupyter内核才能使更改生效。
- 官方支持： 请注意，此方法是针对VSCode Jupyter扩展中一个已知特性请求（Relative Path not work for Remote Kernel #8771）的有效工作方案。如果您希望官方能原生支持此功能，建议在该GitHub Issue上点赞支持，但请避免发送冗余评论。
5. 总结
通过利用jupyter.runStartupCommands配置项，结合VSCode Jupyter扩展提供的内部变量__vsc_ipynb_file__，我们能够优雅地解决在VSCode中远程Jupyter Notebook的相对路径导入问题。这种方法避免了手动切换目录的繁琐，也无需为每个Notebook添加重复的代码，显著提升了远程Python开发的工作效率和体验。
