如何在Visual Studio Code中以主模块模式运行Python以支持相对导入？

安全阿岳

2026-5-15

当然可以通过VS Code的launch.json直接配置实现！

你完全不用依赖额外的run.py文件或者runpy模块，VS Code的Python调试配置原生支持模拟python -m <module>的运行方式，完美解决相对导入的问题。具体配置步骤如下：

步骤1：编辑launch.json

打开VS Code的「运行和调试」面板（左侧工具栏的虫子图标），如果还没有配置文件，点击「创建launch.json文件」并选择「Python」环境；如果已有配置，直接编辑现有条目。

步骤2：配置模块运行模式

把原来的"program"字段替换为"module"字段，指定你要运行的模块路径（和命令行-m后面的参数一致）。举个实际的例子：

假设你的项目结构是这样的：

your_workspace/
└── my_project/
    ├── __init__.py
    ├── main.py  # 你的目标文件，里面用了相对导入
    └── utils/
        └── helper.py

那么对应的launch.json配置应该是：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Run as Module",
            "type": "python",
            "request": "launch",
            "module": "my_project.main",  // 对应命令行的`python -m my_project.main`
            "justMyCode": true
        }
    ]
}

为什么这个配置能生效？

"module"选项就是VS Code专门用来模拟python -m运行模式的：它会自动把模块所在的父目录加入Python的sys.path，同时以模块的方式加载目标文件，这样相对导入（比如from .utils.helper import xxx）就能正常识别了，和你在命令行敲python -m my_project.main的效果完全一致。

如果你的目标文件直接在工作区根目录下（不属于任何子包），那模块名就是文件名本身（不带.py后缀），比如"module": "main"就对应python -m main。