如何将带图片的HTML模板转PDF？Django环境下图片转换问题求助

我明白你被这个问题卡了好几天的痛苦——Django里转HTML到PDF时图片不显示，还报路径错误，确实挺烦人的。针对你用xhtml2pdf遇到的报错，核心问题是它没法直接处理Django的静态/媒体文件URL，得帮它把URL转换成文件系统的绝对路径。下面给你几个可行的解决方案，亲测有效的那种：

一、修复xhtml2pdf的图片路径问题（最推荐） #

xhtml2pdf提供了link_callback参数，专门用来处理URL到本地文件路径的转换，这正是解决你报错的关键。

步骤1：编写路径转换回调函数 #

在你的视图文件里添加这个函数，它会把Django的static或media URL转换成服务器上的绝对文件路径：

from django.conf import settings
import os

def link_callback(uri, rel):
    # 处理静态文件URL
    if uri.startswith(settings.STATIC_URL):
        # 优先从STATICFILES_DIRS找（开发环境适用）
        for static_dir in settings.STATICFILES_DIRS:
            file_path = os.path.join(static_dir, uri.replace(settings.STATIC_URL, ""))
            if os.path.exists(file_path):
                return file_path
        # 再尝试STATIC_ROOT（生产环境已收集静态文件时适用）
        file_path = os.path.join(settings.STATIC_ROOT, uri.replace(settings.STATIC_URL, ""))
    # 处理媒体文件URL
    elif uri.startswith(settings.MEDIA_URL):
        file_path = os.path.join(settings.MEDIA_ROOT, uri.replace(settings.MEDIA_URL, ""))
    else:
        # 非Django静态/媒体URL，直接返回原URI
        return uri

    # 检查文件是否存在，避免报错
    if not os.path.isfile(file_path):
        raise FileNotFoundError(f"无法找到文件: {file_path}")
    return file_path

步骤2：在生成PDF时传入回调函数 #

修改你的PDF生成视图，把link_callback传给pisa.CreatePDF：

from django.http import HttpResponse
from django.template.loader import get_template
from xhtml2pdf import pisa

def generate_pdf(request):
    # 加载模板并渲染HTML
    template = get_template("your_template.html")
    context = {"your_data": "要传递的上下文数据"}
    html_content = template.render(context)

    # 设置PDF响应
    response = HttpResponse(content_type="application/pdf")
    response["Content-Disposition"] = 'attachment; filename="result.pdf"'

    # 生成PDF，传入link_callback处理图片路径
    pisa_status = pisa.CreatePDF(
        html_content,
        dest=response,
        link_callback=link_callback
    )

    # 处理生成错误
    if pisa_status.err:
        return HttpResponse(f"PDF生成失败: {pisa_status.err}", status=500)
    return response

步骤3：模板里正确引用图片 #

确保模板里用Django的static标签引用图片，比如：

<img src="{% static 'images/your_image.png' %}" alt="示例图片">

这样xhtml2pdf就能通过回调函数找到图片的本地路径，正确渲染到PDF里了。

二、ReportLab的图片处理方案 #

如果你更倾向用ReportLab，它需要手动加载图片文件，没法直接从HTML里自动解析图片（除非用它的HTML解析器，但CSS支持很差）。这里给你一个手动插入图片的示例：

from django.http import HttpResponse
from django.conf import settings
from reportlab.pdfgen import canvas
from reportlab.lib.utils import ImageReader
import os

def generate_pdf_with_reportlab(request):
    response = HttpResponse(content_type="application/pdf")
    response["Content-Disposition"] = 'attachment; filename="reportlab_result.pdf"'

    # 创建PDF画布
    pdf_canvas = canvas.Canvas(response, pagesize="A4")

    # 绘制文本内容（示例）
    pdf_canvas.drawString(100, 750, "这是用ReportLab生成的PDF")

    # 加载并绘制图片
    image_path = os.path.join(settings.STATIC_ROOT, "images/your_image.jpg")
    # 用ImageReader读取图片
    img = ImageReader(image_path)
    # 在PDF指定位置绘制图片（x, y坐标，宽高）
    pdf_canvas.drawImage(img, 100, 600, width=200, height=150)

    # 结束当前页并保存PDF
    pdf_canvas.showPage()
    pdf_canvas.save()

    return response

这种方式需要你自己控制PDF的布局，适合对排版要求极高的场景，但不如xhtml2pdf灵活。

额外注意事项 #

• 文件权限：确保运行Django的服务器进程有读取静态/媒体文件的权限，否则即使路径正确也会加载失败。
• 图片格式：xhtml2pdf支持JPG、PNG，不支持SVG，如果用了SVG需要先转换成PNG/JPG。
• 开发环境测试：开发环境下如果没执行collectstatic，STATIC_ROOT是空的，所以回调函数里优先从STATICFILES_DIRS找文件的逻辑很重要。

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