Azure部署Django遇pycairo编译失败问题求助

问题分析 #

pycairo依赖系统级编译库（如libcairo2），Azure Web Apps默认Python环境缺少这些依赖；另外即使手动卸载pycairo，项目中可能有其他依赖包间接引用了它，导致报错持续出现。

解决方案 #

• 排查间接依赖
  用工具找出哪个包间接依赖pycairo，针对性处理：

  pipdeptree | grep pycairo
  

  根据结果，要么更换该依赖包的版本，要么替换为不依赖pycairo的替代包。

• 在Azure Web Apps中安装系统依赖
  针对Linux版Web Apps，通过以下方式安装编译所需库：

  1. 项目根目录创建.deployment文件：

     [config]
     command = apt-get update && apt-get install -y libcairo2-dev libgirepository1.0-dev && pip install -r requirements.txt
     

  2. 或者在Azure门户的Web App配置中设置启动命令：

     apt-get update && apt-get install -y libcairo2-dev libgirepository1.0-dev && gunicorn your_project.wsgi
     

  注意：Windows版Web Apps对pycairo的预编译支持有限，建议切换到Linux版。

• 使用预编译wheel避免编译
  在requirements.txt中指定预编译版本，跳过构建步骤：

  pycairo==1.24.0 --only-binary :all:
  

  也可以下载对应平台的wheel包到项目目录，直接引用本地文件：

  ./pycairo-1.24.0-cp311-cp311-manylinux_2_17_x86_64.whl
  

• 优化Docker部署配置
  如果之前Docker部署失败，大概率是Dockerfile未安装系统依赖，修改如下：

  FROM python:3.11-slim
  RUN apt-get update && apt-get install -y libcairo2-dev libgirepository1.0-dev gcc
  WORKDIR /app
  COPY requirements.txt .
  RUN pip install --no-cache-dir -r requirements.txt
  COPY . .
  CMD ["gunicorn", "your_project.wsgi"]
  

• 清理Azure部署缓存
  部署缓存可能导致旧依赖残留，通过以下方式清理：

  • 登录Azure门户，进入Web App -> 部署中心 -> 高级选项 -> 清理缓存
  • 或通过Kudu控制台删除/home/site/wwwroot/venv目录后重新部署

内容的提问来源于stack exchange，提问作者Derby T matoma