Flask项目运行报错：ModuleNotFoundError: No module named 'Roles'

问题核心原因 #

• attempted relative import beyond top-level package：当app.py作为顶级执行脚本时，Python会将其所在目录视为顶级包，不允许使用跨越该层级的相对导入（如from ..controllers import xxx），从而触发该错误。
• ModuleNotFoundError（VS Code可识别但flask run报错）：VS Code会自动将项目根目录加入Python的sys.path，但flask run默认启动时不会自动添加该路径，导致Python无法识别自定义模块。

具体修复步骤 #

1. 规范项目结构（确保包合法性） #

确保所有自定义模块所在目录都包含__init__.py文件（Python 3.3+虽支持隐式命名空间包，但显式添加可避免兼容性问题），示例结构：

your-project/
├── app.py
├── controllers/
│   ├── __init__.py
│   └── user_controller.py

2. 修正导入语句 #

放弃相对导入，改用绝对导入，示例：

# app.py中导入控制器
from controllers.user_controller import UserController

3. 解决flask run的模块路径问题 #

方法一：手动设置PYTHONPATH

在终端中先配置环境变量，再启动Flask：

• Windows（命令提示符）：

  set PYTHONPATH=C:\full\path\to\your-project
  flask run
  

• Linux/macOS：

  export PYTHONPATH=/full/path/to/your-project
  flask run
  

方法二：直接用Python运行app.py

在app.py末尾添加启动代码：

if __name__ == '__main__':
    app.run(debug=True)

然后执行命令启动：

python app.py

方法三：配置VS Code启动环境

在.vscode/launch.json中添加PYTHONPATH配置，确保项目根目录被加入路径：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Flask",
            "type": "python",
            "request": "launch",
            "module": "flask",
            "env": {
                "FLASK_APP": "app.py",
                "FLASK_ENV": "development",
                "PYTHONPATH": "${workspaceFolder}"
            },
            "args": [
                "run",
                "--no-debugger",
                "--no-reload"
            ]
        }
    ]
}

内容的提问来源于stack exchange，提问作者Trey McCloud