多目录结构下运行Python Dash应用报错排查求助

问题重现 #

目录结构 #

big_dashboard/
    __init__.py
    __main__.py
    src/
        __init__.py
        does_things/
            __init__.py
            do_a_thing.py

代码内容 #

__main__.py：

import dash
from src.does_things.do_a_thing import do

do()

app = dash.Dash(__name__)
app.layout = dash.html.H1('Hello World!')

if __name__ == '__main__':
    app.run(debug = True, host = 'localhost', port = 5000)

do_a_thing.py：

def do():
    print('Thing successfully did')

错误输出 #

Thing successfully did

Dash is running on http://localhost5000/

* Serving Flask app "__main__" (lazy loading)
 * Environment: production
   WARNING: This is a development server. Do not use it in a production deployment.
   Use a production WSGI server instead.
 * Debug mode: on
C:\...\Anaconda3\python.exe: No module named /big_dashboard

问题根源 #

这个错误和导入逻辑无关，核心是调试模式下的自动重载机制冲突。当启用debug=True时，Dash底层的Flask会触发Werkzeug的自动重载器，它会尝试重新加载启动应用的模块。但直接运行__main__.py时，重载器会把文件的绝对路径当作模块名来处理，而Python无法将路径识别为合法模块，因此抛出错误。

解决方案 #

方法1：关闭调试自动重载 #

启动应用时添加use_reloader=False参数，禁用自动重载功能：

if __name__ == '__main__':
    app.run(debug=True, host='localhost', port=5000, use_reloader=False)

缺点是调试时修改代码需要手动重启应用。

方法2：通过包名运行应用 #

在big_dashboard的上级目录，执行以下命令启动应用：

python -m big_dashboard

这种方式会把big_dashboard当作标准Python包加载，重载器能正确识别模块结构，不会出现路径解析错误。

方法3：手动指定Dash应用名称 #

初始化Dash时，将应用名称设置为包名，而非默认的__name__：

app = dash.Dash('big_dashboard')

这样重载器会基于正确的包名重新加载应用，规避路径识别问题。

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