惯性聚合 高效追踪和阅读你感兴趣的博客、新闻、科技资讯
阅读原文 在惯性聚合中打开

推荐订阅源

月光博客
月光博客
MyScale Blog
MyScale Blog
博客园 - Franky
The Cloudflare Blog
IT之家
IT之家
Blog — PlanetScale
Blog — PlanetScale
博客园 - 聂微东
WordPress大学
WordPress大学
Cyber Security Advisories - MS-ISAC
Cyber Security Advisories - MS-ISAC
T
The Blog of Author Tim Ferriss
让小产品的独立变现更简单 - ezindie.com
让小产品的独立变现更简单 - ezindie.com
罗磊的独立博客
Google DeepMind News
Google DeepMind News
P
Proofpoint News Feed
Martin Fowler
Martin Fowler
aimingoo的专栏
aimingoo的专栏
J
Java Code Geeks
腾讯CDC
雷峰网
雷峰网
Microsoft Azure Blog
Microsoft Azure Blog
G
Google Developers Blog
博客园 - 【当耐特】
美团技术团队
云风的 BLOG
云风的 BLOG

博客园 - 星河赵

Vue 打包区分线上测试 Ubuntu + Nginx 使用 Let's Encrypt 生成 HTTPS 证书 微信支付申请相关资料 mysql 常用命令 熟练使用 mysql flask fastapi mysql 常用命令 LangChain AI 客服 Agent 项目学习笔记 海外stripe 聚合支付 ffmpeg 介绍 AE中制作带可替换屏幕的视频模版 记录|AI超写实短视频制作流程+提示词 服务端部署Vue 在Pycharm 中使用 Python Module 方式启动 uvicorn Conda 虚拟环境完整指南 CentOS / OpenCloudOS 服务器如何安装远程桌面 2026 谷歌 Antigravity 最新安装教程! Vscode 常用配置 如何修改 Redis 数据存放路径 Vue 后台项目 Nginx 部署笔记(SPA / Vite 构建) Python -m 用法(极简版) Ubuntu 上安装 MongoDB 并启用事务的完整流程 mac 微信双开新方法 nginx 对静态资源进行压缩 HMAC-SHA256 请求签名与验签实践(Python 可直接复用) python fast api websocket 连接事例 在 Flask 中并发执行任务 Vscode 配置快捷键和JetBrains(pycharm)一样 Linux 服务器的 SSH 登录端口号 从默认的 22 改掉 配置 Docker 镜像加速器 python fast api 部署
Python 项目模块导入问题解决方案
星河赵 · 2026-01-27 · via 博客园 - 星河赵

问题描述

在 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

,说明配置成功! ✅