当使用 python app 方式运行含 __main__.py 的包时，Python 会将包目录（而非父目录）加入 sys.path，导致 from app import ... 因路径错位而报 ModuleNotFoundError；正确做法是移除冗余包名、避免在 __init__.py 中执行业务逻辑，并采用相对导入或重构入口逻辑。
当使用 `python app` 方式运行含 `__main__.py` 的包时，python 会将包目录（而非父目录）加入 `sys.path`，导致 `from app import ...` 因路径错位而报 `modulenotfounderror`；正确做法是移除冗余包名、避免在 `__init__.py` 中执行业务逻辑，并采用相对导入或重构入口逻辑。
在 Flask 项目中，若将 __main__.py 放在 app/app/ 目录下并执行 python app，Python 会把 app/（即子目录）作为顶层包路径加入 sys.path，此时当前包名为 app，但 from app import serve 实际试图从顶层命名空间导入 app 模块——而该模块并不存在于 sys.path 根目录下，因此触发 ModuleNotFoundError。
✅ 正确做法：使用相对导入 + 清晰职责分离
首先，不要在 __init__.py 中执行应用初始化或注册逻辑。__init__.py 应仅用于定义包接口（如 __all__）或进行轻量级模块级初始化，而非启动 Flask 实例或注册蓝图。将业务逻辑移至专用模块（如 app/core.py 或 app/app.py），保持结构清晰、可测试。
✅ 推荐目录结构调整（精简版）
app/ ├── app/ # 包根目录 │ ├── __init__.py # 空文件或仅导出关键对象 │ ├── __main__.py # 入口：相对导入 + 启动 │ ├── core.py # ✅ 主应用逻辑（Flask 实例、蓝图注册等） │ ├── routes.py │ └── models.py
✅ app/__main__.py（正确写法）
# app/__main__.py
from .core import serve # ✅ 相对导入：当前包内查找 core 模块
if __name__ == "__main__":
serve()✅ app/__init__.py（推荐留空或最小化）
# app/__init__.py —— 保持简洁，不执行任何逻辑 # 可选：显式导出，便于 from app import serve from .core import serve # 若需外部导入，可在此 re-export
✅ app/core.py（核心逻辑集中地）
# app/core.py
from flask import Flask
from .routes import home_page, download_page, upload_page, favicon_page
def create_app():
app = Flask(__name__)
app.register_blueprint(home_page)
app.register_blueprint(download_page)
app.register_blueprint(upload_page, url_prefix="/upload")
app.register_blueprint(favicon_page)
return app
app = create_app() # 实例化（也可延迟创建）
def serve():
app.run(host="0.0.0.0", port=1212, debug=True)⚠️ 关键注意事项
- 禁止 from app import ... 在 app/app/ 内部使用：因为 python app 使 app/ 成为包根，app 已是当前包名，再 from app import ... 会尝试导入同名顶层模块（不存在）。
- 避免在 __init__.py 中导入子模块并执行副作用（如 app.run()），这会导致循环导入风险，且违反单一职责原则。
-
调试技巧：运行前可打印 sys.path 和 __package__ 验证环境：
# 在 __main__.py 开头添加 import sys print("sys.path:", sys.path) print("__package__:", __package__) # 应为 'app'
✅ 验证运行方式
确保在项目根目录（app/ 的父目录）执行：
python -m app # ✅ 推荐：明确以模块方式运行 # 或 cd app && python -m app # 同效
❌ 错误方式：python app/app/__main__.py（绕过包机制，__package__ 为 None，相对导入失效）
立即学习“Python免费学习笔记（深入）”；
遵循以上结构，即可彻底解决 ModuleNotFoundError: No module named 'app'，同时提升代码可维护性与可测试性。
