在Google Flexible App Engine（Python3.6+Flask）中无法导入matplotlib

我之前也碰到过一模一样的坑——Matplotlib在无头（无GUI）的服务器环境里特别容易踩依赖问题，尤其是GAE Flex这种容器化环境，默认后端要依赖图形界面组件，直接部署肯定会失败。下面是我整理的一步步解决办法：

1. 强制Matplotlib使用无头后端 #

Matplotlib默认会尝试调用需要显示输出的后端（比如TkAgg），但GAE Flex里根本没有图形环境，所以必须在代码最开头就指定非交互式后端。在你的Flask应用初始化或者用到Matplotlib的代码前，一定要先加这段：

import matplotlib
# 切换到纯后端渲染模式，完全避开GUI依赖
matplotlib.use('Agg')
import matplotlib.pyplot as plt

⚠️ 注意：必须在import plt之前设置matplotlib.use('Agg')，否则会完全无效。

2. 补充系统级依赖 #

Matplotlib依赖一些底层系统库，比如libpng、freetype、libjpeg这些，GAE Flex的Python运行时默认没预装。你可以通过两种方式补上：

方式一：直接在app.yaml里配置（推荐） #

在现有app.yaml里添加系统依赖配置，GAE构建容器时会自动安装：

service: my_service
runtime: python
env: flex
entrypoint: gunicorn -b :$PORT main:app
runtime_config:
  python_version: 3
# 添加Matplotlib需要的系统库
system_packages:
  - libpng-dev
  - freetype-dev
  - libjpeg-dev

方式二：自定义Dockerfile（更灵活） #

如果需要更精细的环境控制，也可以写自定义Dockerfile，基于GAE的Python基础镜像：

FROM gcr.io/google-appengine/python
RUN apt-get update && apt-get install -y --no-install-recommends \
    libpng-dev \
    freetype-dev \
    libjpeg-dev \
    && rm -rf /var/lib/apt/lists/*
COPY requirements.txt /app/
RUN pip install --upgrade pip && pip install -r requirements.txt
COPY . /app/
ENTRYPOINT ["gunicorn", "-b", ":$PORT", "main:app"]

然后在app.yaml里指定用自定义镜像：

service: my_service
env: flex
runtime: custom

3. 确保requirements.txt包含所有必要依赖 #

你的requirements.txt必须列出所有Python依赖，包括Matplotlib和云存储客户端库：

Flask==2.0.1
gunicorn==20.1.0
pandas==1.3.5
numpy==1.21.6
matplotlib==3.4.3
google-cloud-storage==2.3.0

版本号可以根据你的实际需求调整，尽量选稳定兼容的版本。

4. 生成并上传PNG到云存储的示例代码 #

给你一个极简的示例，生成图表后直接上传到GCS，全程不用本地存储：

from google.cloud import storage
import matplotlib
matplotlib.use('Agg')
import matplotlib.pyplot as plt
import io

def generate_and_upload_plot(bucket_name, blob_name):
    # 生成示例图表
    plt.plot([1, 2, 3, 4], [10, 20, 25, 30])
    plt.title('Sample Data Plot')
    
    # 将图表保存到内存缓冲区，不用写本地文件
    img_buffer = io.BytesIO()
    plt.savefig(img_buffer, format='png')
    img_buffer.seek(0)  # 重置缓冲区指针到开头
    
    # 上传到GCS
    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(blob_name)
    blob.upload_from_file(img_buffer, content_type='image/png')
    
    plt.close()  # 关闭图表释放内存
    return f'Image uploaded to gs://{bucket_name}/{blob_name}'

⚠️ 别忘了给GAE服务账号赋予云存储的写入权限，不然会上传失败。

5. 本地测试建议 #

部署前可以在本地模拟无头环境测试，避免白跑一趟：

# 设置环境变量模拟无头环境
export MPLBACKEND=Agg
# 运行你的Flask应用或者单独测试脚本
python main.py

如果本地能正常生成并上传图片，那部署到GAE Flex基本就没问题了。

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