Flask根目录模块引用触发循环导入ImportError报错

问题成因 #

当前代码的导入链路存在环形引用：

• wsgi.py 启动时首先尝试导入 app.main 中的 app 实例
• main.py 在完成 app 实例初始化前，就先导入了 .sftp、.config 等内部模块
• 旧版config.py反向导入wsgi中的app、修改后的sftp.py反向导入main中的app，此时被导入的模块还未完成初始化，直接触发部分初始化模块导入错误。

分步修改方案 #

1. 重构config.py，移除顶层app依赖 #

删除config.py中对wsgi或app实例的顶层导入，仅存放不依赖应用实例的静态配置，从源头切断循环点：

import os

# SFTP连接配置可通过环境变量注入，适配不同部署环境
SFTP_HOSTNAME = os.getenv("SFTP_HOST", "")
SFTP_USERNAME = os.getenv("SFTP_USER", "")
SFTP_PASSWORD = os.getenv("SFTP_PASS", "")

不要在config.py顶层定义依赖app实例的路径变量，模块加载阶段app还未完成初始化。

2. 重写sftp.py，通过Flask内置代理获取路径 #

不要在sftp.py顶层导入app实例，改用Flask提供的current_app代理获取应用路径——该代理会在代码运行时自动指向当前活跃的应用实例，不需要手动导入app，完全不会触发循环引用。
sftp.py修改后完整代码：

import pysftp as sftp
from .config import *
from .utils import upload_working_days
import time
import os
from datetime import datetime
from flask import current_app

def sync_work_days():
    # 动态获取应用根目录，自动适配Windows/Linux、任意部署路径，无硬编码
    # current_app.root_path 对应/app目录的绝对路径，拼接static目录即为静态文件存储路径
    local_save_dir = os.path.join(
        current_app.root_path,
        "static",
        "files",
        "company"
    )
    # 自动创建目标目录，避免部署时目录不存在报错
    os.makedirs(local_save_dir, exist_ok=True)

    cnopts = sftp.CnOpts()
    cnopts.hostkeys = None
    conn = sftp.Connection(
        host=SFTP_HOSTNAME,
        username=SFTP_USERNAME,
        password=SFTP_PASSWORD,
        cnopts=cnopts
    )
    print("SFTP连接建立成功")

    remote_base_path = "/files/company"
    remote_files = conn.listdir_attr(remote_base_path)
    if not remote_files:
        conn.close()
        return "empty"

    for file_attr in remote_files:
        filename = file_attr.filename
        remote_file_full = os.path.join(remote_base_path, filename)
        local_file_full = os.path.join(local_save_dir, filename)
        
        # 下载远程文件到本地静态目录
        conn.get(remote_file_full, local_file_full)
        upload_working_days(local_file_full)
        time.sleep(5)
        print(f"文件{filename}处理完成")
        
        # 移动远程文件到归档目录
        remote_archive_path = os.path.join(remote_base_path, "archives", filename)
        conn.rename(remote_file_full, remote_archive_path)

    conn.close()
    return "sync_success"

路径说明：如果需要存放到instance目录，把current_app.root_path换成current_app.instance_path即可，两种方式都是动态获取绝对路径，不需要硬编码。

3. 调整main.py的导入顺序 #

把Flask应用实例的初始化放到所有内部模块导入之前，保证模块加载时app实例已经存在：

from flask import Flask, render_template, request, session, flash, url_for, redirect
from werkzeug.utils import secure_filename

# 第一步：先初始化app实例
app = Flask(__name__)
app.secret_key = b'very_secret_key'

# 第二步：再导入其他内部模块
from .utils import *
from .config import *
from .sftp import sync_work_days

# 原有路由、其他业务逻辑[...]

4. 非请求场景调用注意事项 #

如果sync_work_days是通过定时任务、启动脚本触发，不是在视图函数内调用，需要手动推入应用上下文，保证current_app能正常获取到实例，示例：

# 例如在main.py末尾加启动时同步逻辑
if __name__ == "__main__":
    with app.app_context():
        sync_work_days()
    app.run()

如果是在视图路由里调用该函数，不需要额外处理，请求本身处于应用上下文内。

方案验证 #

修改后导入链路为单向无环：

• wsgi.py 导入main中初始化完成的app实例
• main.py 初始化app后再导入config、sftp、utils模块
• 所有业务模块不反向导入app实例，仅在函数运行时通过current_app获取应用属性，彻底消除循环导入问题，同时路径完全动态生成，适配任意部署环境。

内容的提问来源于stack exchange，提问作者Kaiss B.