Python 项目模块导入问题解决方案

问题描述

在 Python 项目中直接运行子目录下的文件时,会出现 

ModuleNotFoundError: No module named 'xxx'

 错误,因为 Python 找不到项目根目录的模块。

 

解决方案总结

方案一:在代码中添加路径配置(推荐用于测试脚本)

在 Python 文件的 

if __name__ == '__main__':

 块中添加以下代码:

 

if __name__ == '__main__':
    # 添加项目根目录到 sys.path,使得可以直接运行
    import sys
    from pathlib import Path
    project_root = Path(__file__).parent.parent.parent.parent  # 根据文件层级调整
    if str(project_root) not in sys.path:
        sys.path.insert(0, str(project_root))
    
    # 你的测试代码...

 

 

说明: 

parent

 的数量取决于文件在项目中的层级深度。

 

方案二:VS Code 配置(推荐用于日常开发)

1. 配置 

 

.vscode/launch.json(用于 F5 调试)

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Current File",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "cwd": "${workspaceFolder}",
            "env": {
                "PYTHONPATH": "${workspaceFolder}"
            },
            "python": "${workspaceFolder}/venv/bin/python"
        }
    ]
}

 

2. 配置 .vscode/settings.json(用于终端运行)

{
    "terminal.integrated.env.osx": {
        "PYTHONPATH": "${workspaceFolder}"
    },
    "terminal.integrated.env.linux": {
        "PYTHONPATH": "${workspaceFolder}"
    },
    "python.envFile": "${workspaceFolder}/.env"
}

方案三:命令行运行

方式 1: 以模块方式运行(最标准)

cd /项目根目录
python -m package.subpackage.module_name

 

方式 2: 设置 PYTHONPATH 环境变量

# 临时设置(单次有效)
PYTHONPATH=/项目根目录 python /完整路径/文件.py

# 或者先导出再运行
export PYTHONPATH=/项目根目录:$PYTHONPATH
python /完整路径/文件.py

在 VS Code 中运行 Python 文件的方法

配置好后,可以通过以下方式运行:

1. F5 调试运行 - 使用 
    
   launch.json 配置,可设置断点
2. 右键 → Run Python File in Terminal - 使用 
    
   settings.json 配置
3. 点击右上角 ▶️ 按钮 - 快速运行

关键要点

• 项目根目录: 包含主包名的那一层目录(通常是 git 仓库根目录)
• PYTHONPATH: 告诉 Python 去哪里找模块
• 双重保障: VS Code 配置 + 代码内配置,确保任何方式运行都不会出错

验证是否配置成功

运行文件后,如果不再出现 

ModuleNotFoundError

,说明配置成功! ✅