导入子模块SQLAlchemy db时为何出现Flask弱引用错误？

问题场景 #

项目目录结构：

-FSBS
   -API
      - __init__.py
      - app.py
      - extensions.py
      - routes.py

核心代码：

• extensions.py中初始化全局扩展实例：

from flask_sqlalchemy import SQLAlchemy
from flask_bcrypt import Bcrypt

db = SQLAlchemy()
bcrypt = Bcrypt()

• app.py中创建Flask应用并注册扩展：

# 原导入（运行正常）
from extensions import db
# 修改后的导入（触发错误）
# from FSBS.API.extensions import db

def create_api():
    api = Flask(__name__)
    api.config['SQLALCHEMY_DATABASE_URI'] = os.environ.get("DB_URL", "default")
    
    register_extensions(api)
    register_models(api)
    register_urls(api)
    
    return api

create_api().run()

• 注册相关方法：

def register_models(api):
    with api.app_context():
        db.create_all()

def register_extensions(api):
    db.init_app(api)
    bcrypt.init_app(api)

将app.py中的导入改为绝对路径from FSBS.API.extensions import db后，所有涉及db的操作抛出KeyError: <weakref at 0x...; to 'Flask' at 0x...>错误。

原因分析 #

问题根源是Python模块被重复加载，生成了两个独立的db实例：

• 使用相对导入from extensions import db时，Python从当前API包加载extensions模块，生成的db实例会被register_extensions绑定到Flask应用。
• 使用绝对导入from FSBS.API.extensions import db时，如果直接运行app.py，Python会把FSBS.API和当前目录的API视为两个不同包路径，导致extensions模块被加载两次，生成另一个未经过init_app初始化的db实例。代码使用这个未绑定应用的实例时，就会抛出KeyError。

解决方案 #

1. 统一全项目导入方式 #

所有模块导入扩展时，使用完全一致的路径：

• 包内部模块用相对导入：from .extensions import db
• 跨包或全局用绝对导入：from FSBS.API.extensions import db

确保整个项目引用的是同一个db实例，避免模块重复加载。

2. 完善包结构 #

在FSBS根目录下添加空的__init__.py文件，让Python将FSBS识别为合法Python包，保证绝对导入路径的正确性。

3. 用包方式启动项目 #

不要直接运行app.py，而是通过Python模块方式启动：

python -m FSBS.API.app

这种方式会让Python以正确的包层级加载模块，避免路径问题导致的模块重复加载。

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