Azure Function Python用poppler-utils转PDF为图片报错如何解决

根本原因 #

该报错是pdf2image库的转换逻辑依赖系统级工具包poppler-utils，而Azure Function App的默认运行环境未预装该依赖，也没有将其可执行文件路径纳入系统PATH，导致调用转换接口时无法找到底层依赖。 #

修复方案 #

方案1：适用Linux消费/弹性/专用计划（最常用部署场景） #

• 第一步：确认项目根目录的requirements.txt已添加pdf2image依赖：

pdf2image>=1.16.0

• 第二步：在项目根目录新建startup.sh启动脚本，写入以下内容：

#!/bin/bash
apt-get update
apt-get install -y poppler-utils
exec /azure-functions-host/Microsoft.Azure.WebJobs.Script.WebHost

• 第三步：为启动脚本配置执行权限，如果是Windows本地开发上传代码，可以将启动命令配置为：

chmod +x /home/site/wwwroot/startup.sh && /home/site/wwwroot/startup.sh

如果是Git部署，可以在本地执行git update-index --chmod=+x startup.sh后再提交。

• 第四步：进入Azure门户的Function App配置页，找到配置→常规设置→启动命令，填入上述对应启动命令后，保存配置并重启Function App即可生效。

方案2：适用Windows部署计划 #

Windows环境不支持apt包管理，需要手动集成poppler二进制包：

• 第一步：下载Windows版预编译poppler二进制包，解压后将包内的bin文件夹整体放到Function项目根目录，命名为poppler_bin
• 第二步：在调用转换接口的Python代码中，手动将poppler路径加入系统PATH，也可以直接显式传入路径参数：

import os
from pdf2image import convert_from_bytes

# 拼接poppler可执行文件目录的绝对路径
poppler_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), "poppler_bin")
os.environ["PATH"] += os.pathsep + poppler_path

# 调用转换接口时可显式指定poppler_path参数，优先读取指定路径避免PATH异常
pages = convert_from_bytes(file_bytes, 500, poppler_path=poppler_path)

• 第三步：重新打包部署代码即可生效。

方案3：适用自定义容器部署场景 #

如果你的应用有更多系统级依赖，可以直接构建自定义容器镜像部署，参考Dockerfile如下：

FROM mcr.microsoft.com/azure-functions/python:4-python3.10

# 安装系统依赖
RUN apt-get update && apt-get install -y --no-install-recommends \
    poppler-utils \
    && rm -rf /var/lib/apt/lists/*

# 配置Function运行环境变量
ENV AzureWebJobsScriptRoot=/home/site/wwwroot \
    AzureFunctionsJobHost__Logging__Console__IsEnabled=true

# 安装Python依赖
COPY requirements.txt /
RUN pip install --no-cache-dir -r /requirements.txt

# 复制项目代码
COPY . /home/site/wwwroot

构建镜像推送到容器镜像仓库后，选择容器部署模式部署Function App即可，无需额外配置启动脚本。 #

验证排查方法 #

可以在Function代码中加入如下测试逻辑，快速确认依赖是否安装成功：

import os
pdftocairo_exists = any(
    os.path.exists(os.path.join(path, "pdftocairo")) 
    for path in os.environ["PATH"].split(os.pathsep)
)
print(f"poppler是否安装成功：{pdftocairo_exists}")

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