使用Flask CLI遇模块未找到错误：无法加载配置类

问题描述 #

为什么Flask在应用工厂的app.config.from_object(environment_import_path)代码行中找不到flask_app.config.DevelopmentConfig？

在应用工厂中，我已将instance_relative_config设置为True，并将instance_path指向src包/目录，也尝试过基础的app = Flask(__name__)写法，但仍出现相同错误。

当前环境为Python 3.12、Flask 3.0.3，直接运行run_flask_app.py时应用可正常启动，但在src目录下执行以下命令：

flask --app 'flask_app.app:create_app("flask_app.config.DevelopmentConfig")' run

会出现模块未找到错误，提示找不到flask_app模块。

应用结构如下：

src
|-__init__.py
|-run_flask_app.py
|-flask_app
  |-__init__.py
  |-app.py（注：该文件位于flask_app包内）
  |-config.py

app.py中的应用工厂代码：

def create_app(environment_import_path):
    print('environment_import_path', environment_import_path)
    print('basedir',  os.path.abspath(os.path.join('../', os.path.dirname(__file__))))
    print('basedir2',  os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

    app = Flask(__name__, instance_relative_config = True,
                instance_path=os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

    print('app.instance_path', app.instance_path)

    app.config.from_object(environment_import_path)

    db.init_app(app)
    migrate.init_app(app, db)

    register_blueprints(app)

    return app

run_flask_app.py代码：

from flask_app.app import create_app

environment_import_path = 'flask_app.config.DevelopmentConfig'

app = create_app(environment_import_path)

if __name__ == '__main__':
    app.run(host="localhost", port=8000)

解决方案 #

问题根源 #

直接运行run_flask_app.py时，Python会自动将脚本所在的src目录加入模块搜索路径sys.path，因此能找到flask_app模块；但使用flask命令行启动时，当前工作目录虽是src，但Python的模块搜索路径未包含该目录，导致无法识别flask_app。

修复方法 #

1. 添加PYTHONPATH环境变量
   在src目录下执行命令前，先将当前目录加入Python的模块搜索路径：

# Linux/macOS
export PYTHONPATH=$(pwd)
flask --app 'flask_app.app:create_app("flask_app.config.DevelopmentConfig")' run

# Windows PowerShell
$env:PYTHONPATH = (Get-Location).Path
flask --app 'flask_app.app:create_app("flask_app.config.DevelopmentConfig")' run

2. 简化应用启动命令
   在flask_app/__init__.py中预先初始化应用：

# flask_app/__init__.py
from .app import create_app

app = create_app('flask_app.config.DevelopmentConfig')

之后在src目录下直接执行：

flask --app flask_app run

这种方式避免了命令行中传递复杂参数，更简洁可靠。

3. 调整instance_path设置（非必需）
   instance_relative_config=True时，Flask会自动在src目录下寻找instance文件夹，无需手动指定instance_path，可删除该参数简化代码。

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