解决 VSCode 调试时 Python 文件路径问题及 `FileNotFoundError` 报错 (在原本非调试情况下可运行)

文章目录

在使用 VSCode 进行 Python 开发时，很多开发者都会遇到一个常见的问题：在调试模式下，程序无法读取文件或路径，导致 FileNotFoundError 错误。然而，当不使用调试模式而是直接运行 Python 文件时，一切又正常工作。本文将详细探讨这个问题，并给出解决方法。

背景与问题描述

假设我们有一个项目，位于路径 /home/iip/tp/022-MLog，其目录结构如下：

022-MLog/
│
├── data/
│   └── BGL/
│       └── events_semantic.json  # 项目依赖的文件
├── demo/
│   └── mog_lstm_cnn_BGL.py       # 需要调试的 Python 脚本
├── Model/
│   └── dataset/
│       └── sample.py             # 读取文件的模块
│   └── tools/
│       └── train.py              # 调用 sample.py 的代码
└── .vscode/
    └── launch.json               # VSCode 调试配置文件

在调试时，demo/mog_lstm_cnn_BGL.py 会调用 Model/dataset/sample.py 读取文件 ../data/BGL/events_semantic.json，但调试时抛出了以下错误：

发生异常: FileNotFoundError
[Errno 2] No such file or directory: '../data/BGL/events_semantic.json'

错误提示文件路径有问题。令人疑惑的是，直接运行 demo/mog_lstm_cnn_BGL.py 没有任何问题，程序能够正常运行。

一、问题分析

这是一个典型的工作目录问题。在 Python 中，相对路径是基于当前工作目录解析的，而 VSCode 调试和直接运行程序时的工作目录可能不同。

二、解决方案

1. 修改 launch.json 文件，确保正确的工作目录

VSCode 使用 launch.json 文件来配置调试时的行为。我们可以通过指定工作目录来解决路径问题。

首先，确保 launch.json 文件位于 .vscode/launch.json 下，如果没有该文件，可以在 VSCode 侧边栏的“运行和调试”面板中点击“创建 launch.json 文件”按钮。

编辑 launch.json，将工作目录 cwd 设置为 demo 文件夹，这样调试时的工作目录与直接运行时一致。配置如下：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Debug",
            "type": "python",
            "request": "launch",
            "program": "${workspaceFolder}/demo/mog_lstm_cnn_BGL.py",  // 你的主程序文件
            "cwd": "${workspaceFolder}/demo",  // 将工作目录设置为 demo 文件夹
            "console": "integratedTerminal",
            "justMyCode": true
        }
    ]
}

这样，调试时的工作目录将与实际运行时保持一致，从而解决了路径问题。

2. 检查和调整相对路径

在代码中，使用相对路径时应该确保其相对于当前的工作目录。在上面的报错示例中，路径 ../data/BGL/events_semantic.json 是相对于某个目录的。但如果你不确定当前工作目录是什么，可能会导致路径解析错误。

为了使路径更加健壮，可以使用 os.path 模块动态构建文件路径，避免路径依赖于工作目录的变化：

import os

# 获取当前文件所在的目录
current_dir = os.path.dirname(os.path.abspath(__file__))
data_dir = os.path.join(current_dir, '../data/BGL/')
file_path = os.path.join(data_dir, 'events_semantic.json')

with open(file_path, 'r') as load_f:
    # 读取文件的逻辑

os.path.dirname(__file__) 可以获取当前 Python 文件所在的目录，无论工作目录如何变化，都能构建出正确的文件路径。

3. 直接调试与 launch.json 调试的区别

了解了路径问题的原因后，我们再来分析一下 VSCode 中两种常见的调试方式：

（1）直接调试 Python 文件

这是最简单的调试方式，无需额外配置。在 VSCode 中直接打开 Python 文件，设置断点，按 F5 或点击 “运行和调试” 按钮即可开始调试。

特点：

（2）使用 launch.json 配置调试

当项目结构复杂，或需要传递命令行参数、环境变量时，可以使用 launch.json 进行调试配置。

特点：

常见的 launch.json 配置项包括：

三、总结

VSCode 在调试 Python 项目时，工作目录不一致可能导致文件路径问题，尤其是当代码中使用相对路径时。这种问题可以通过调整工作目录或使用绝对路径来解决。具体步骤包括：

1. 设置正确的工作目录：在 launch.json 文件中通过 cwd 配置指定正确的工作目录。
2. 动态构建文件路径：使用 os.path 模块确保路径的健壮性，避免相对路径带来的问题。
3. 理解调试方式的差异：根据项目的复杂程度选择合适的调试方式，直接调试适用于简单场景，而 launch.json 更适合复杂项目。

作者：迷路爸爸180