Python 3使用pisa生成含多图片URL的PDF时图片渲染异常

问题根源 #

• pisa默认加载远程图片时存在缓存复用问题，不同URL被错误识别为同一资源
• GCS URL可能触发重定向，pisa处理重定向时出现资源混淆
• Cloud Function运行环境的网络并发特性，导致图片加载顺序错乱

解决方案 #

方案1：预下载GCS图片转为Base64嵌入HTML

直接将图片下载后转为Base64嵌入HTML，彻底规避远程加载的不确定性。

from xhtml2pdf import pisa
from google.cloud import storage
import base64
from io import BytesIO

def get_gcs_image_base64(bucket_name, blob_path):
    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(blob_path)
    img_bytes = blob.download_as_bytes()
    mime_type = blob.content_type or "image/jpeg"
    return f"data:{mime_type};base64,{base64.b64encode(img_bytes).decode('utf-8')}"

def make_PDF(html_template):
    # 替换HTML中的图片URL占位符为Base64内容
    # 示例：html = html_template.replace("{{image1}}", get_gcs_image_base64("my-bucket", "path/to/image1.jpg"))
    
    packet = BytesIO()
    pisa_status = pisa.CreatePDF(
        html_template,
        dest=packet,
        encoding='UTF-8',
        raise_exception=True
    )
    if pisa_status.err:
        raise Exception(f"PDF生成错误: {pisa_status.err}")
    
    result = packet.getvalue()
    packet.close()
    return result

方案2：自定义资源加载器禁用缓存

通过自定义pisa的资源加载函数，强制每个图片URL单独请求，避免内部缓存混淆。

from xhtml2pdf import pisa
from io import BytesIO
import requests

def custom_resource_loader(uri, rel):
    headers = {'Cache-Control': 'no-cache'}
    response = requests.get(uri, headers=headers)
    response.raise_for_status()
    return BytesIO(response.content)

def make_PDF(html):
    packet = BytesIO()
    pisa_status = pisa.CreatePDF(
        html,
        dest=packet,
        encoding='UTF-8',
        link_callback=custom_resource_loader
    )
    if pisa_status.err:
        raise Exception(f"PDF生成错误: {pisa_status.err}")
    
    result = packet.getvalue()
    packet.close()
    return result

注意：需在Cloud Function的requirements.txt中添加requests依赖。

方案3：使用GCS签名URL（非公开图片场景）

若GCS图片未公开，普通URL会返回403，导致pisa复用已加载资源。需生成带有效期的签名URL：

from google.cloud import storage
from datetime import timedelta

def get_signed_gcs_url(bucket_name, blob_path):
    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(blob_path)
    signed_url = blob.generate_signed_url(
        version="v4",
        expiration=timedelta(hours=1),
        method="GET"
    )
    return signed_url

将生成的签名URL替换HTML中的原始图片地址即可。

额外注意事项 #

• 确保Cloud Function的服务账号拥有roles/storage.objectViewer权限，可读取GCS对象
• 避免HTML中使用重复的img标签id或name属性，防止pisa误判缓存
• 可添加日志打印每个图片的加载状态，快速定位异常资源

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