Flask集成matplotlib后Apache部署页面无法加载问题排查

核心原因 #

Matplotlib默认启用GUI交互式后端（比如Windows下的TkAgg），而Apache作为系统服务运行时，处于无桌面会话的环境中，无法初始化GUI相关组件，导致进程阻塞，最终引发页面长时间无响应。直接运行Flask时是在桌面会话下，GUI后端能正常初始化，所以不会出现问题。

解决步骤 #

1. 强制指定非交互式后端 #

在导入任何Matplotlib相关模块之前，先设置环境变量指定非交互式后端（比如Agg），这是解决问题的关键。

修改代码开头：

import os
# 先设置环境变量指定非交互式后端
os.environ['MPLBACKEND'] = 'Agg'

import io
from flask import Response
from matplotlib.backends.backend_agg import FigureCanvasAgg as FigureCanvas
from matplotlib.figure import Figure
import numpy as np
# 原代码使用了plt但未导入，补充导入
import matplotlib.pyplot as plt
plt.rcParams["figure.figsize"] = [7.50, 3.50]
plt.rcParams["figure.autolayout"] = True

或者更稳妥的方式，不依赖pyplot，直接在Figure对象上配置参数：

import os
os.environ['MPLBACKEND'] = 'Agg'

import io
from flask import Response
from matplotlib.backends.backend_agg import FigureCanvasAgg as FigureCanvas
from matplotlib.figure import Figure
import numpy as np

app = Flask(__name__)

@app.route('/print-plot')
def plot_png():
   fig = Figure(figsize=(7.50, 3.50))
   fig.set_tight_layout(True)  # 替代autolayout配置
   axis = fig.add_subplot(1, 1, 1)
   xs = np.random.rand(100)
   ys = np.random.rand(100)
   axis.plot(xs, ys)
   output = io.BytesIO()
   FigureCanvas(fig).print_png(output)
   return Response(output.getvalue(), mimetype='image/png')

2. 检查Apache服务运行权限 #

Windows下Apache默认用LocalSystem账户运行，可能缺少访问Matplotlib字体文件或临时目录的权限：

• 可尝试将Apache服务的运行账户改为你的当前用户（有桌面权限的账户），但生产环境不推荐此操作；
• 确保Matplotlib缓存目录（一般在C:\Users\<你的用户名>\.matplotlib）对Apache运行账户有读写权限。

3. 查看Apache错误日志定位细节 #

打开Apache的错误日志文件（默认路径为Apache24\logs\error.log），里面会记录具体报错信息，比如后端初始化失败的详细原因，有助于进一步排查问题。

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