执行flask db init失败：无法找到sample_models模块

问题场景 #

在Flask项目中使用Flask-Migrate时，执行flask db init命令出现以下错误：

Error: While importing 'app.api', an ImportError was raised:

Traceback (most recent call last):
  File "/usr/local/lib/python3.12/site-packages/flask/cli.py", line 245, in locate_app
    __import__(module_name)
  File "/app/api.py", line 5, in <module>
    from sample_models.db import db
ModuleNotFoundError: No module named 'sample_models'

项目结构如下：

sample_project/
├── __init__.py
├── api.py
└── sample_models/
    ├── __init__.py
    ├── db.py
    └── sample_model.py

解决步骤 #

1. 把项目根目录加入Python搜索路径 #

Python找不到sample_models模块，核心原因是项目根目录不在Python的默认搜索路径中，可通过两种方式解决：

• 命令行临时配置（Linux/macOS）：

  export PYTHONPATH=/path/to/sample_project:$PYTHONPATH
  

  （Windows命令行）：

  set PYTHONPATH=C:\path\to\sample_project;%PYTHONPATH%
  

  替换其中的路径为你的实际项目根目录路径。
• 代码内自动配置：
  在api.py最开头添加以下代码，自动将项目根目录加入路径：

  import os
  import sys
  sys.path.append(os.path.dirname(os.path.abspath(__file__)))
  

2. 补充缺失的模块导入 #

api.py中使用了os模块但未导入，需在文件开头添加：

import os

3. 确保Flask-Migrate能扫描到数据库模型 #

Flask-Migrate需要加载所有模型才能生成迁移文件，需确保模型被正确导入到应用上下文：

• 修改sample_models/__init__.py，统一导入db实例和所有模型：

  from .db import db
  from .sample_model import SampleModel
  

• 在api.py的create_app函数中，初始化migrate后导入模型，确保模型被加载：

  def create_app(test_config=None):
      migrate = Migrate()
      app = Flask(__name__, instance_relative_config=True)
      
      # ... 原有配置代码 ...
      
      db.init_app(app)
      migrate.init_app(app, db)
      
      # 导入模型，让Flask-Migrate能检测到
      from sample_models import SampleModel
      
      with app.app_context():
          db.create_all()
      
      # ... 路由和返回代码 ...
  

4. 正确设置FLASK_APP环境变量 #

由于你的应用使用**工厂函数create_app**创建，需指定正确的FLASK_APP格式：

• Linux/macOS：

  export FLASK_APP=api:create_app
  

• Windows：

  set FLASK_APP=api:create_app
  

完成以上步骤后，重新执行flask db init即可正常初始化迁移环境。

内容的提问来源于stack exchange，提问作者Mạnh Đỗ Duy