Django使用render_to_pdf生成PDF时图片无法显示问题求助

问题描述 #

使用render_to_pdf工具结合Django模板生成PDF时，模板中通过{% static %}标签引入的图片无法显示，控制台报错“Need a valid file name”。

问题原因 #

xhtml2pdf的pisaDocument无法直接识别Django生成的静态资源URL（如/static/images/tof.png），它需要本地文件系统的真实路径才能加载图片。

解决方案 #

修改utils.py中的render_to_pdf函数，添加路径解析回调函数，将静态URL转换为本地文件路径：

1. 更新utils.py代码 #

from io import BytesIO
from django.http import HttpResponse
from django.template.loader import get_template
from django.conf import settings
import os
from xhtml2pdf import pisa

def link_callback(uri, rel):
    # 处理静态文件路径转换
    if uri.startswith(settings.STATIC_URL):
        # 替换STATIC_URL为STATIC_ROOT的本地路径
        path = os.path.join(settings.STATIC_ROOT, uri.replace(settings.STATIC_URL, ""))
    elif uri.startswith(settings.MEDIA_URL):
        # 处理媒体文件（可选）
        path = os.path.join(settings.MEDIA_ROOT, uri.replace(settings.MEDIA_URL, ""))
    else:
        return uri  # 非静态/媒体文件返回原URI
    
    # 验证文件是否存在
    if not os.path.isfile(path):
        raise Exception(f"静态文件未找到: {path}")
    return path

def render_to_pdf(template_src, context_dict={}):
    template = get_template(template_src)
    html = template.render(context_dict)
    result = BytesIO()
    # 传入link_callback参数，让pisa能解析静态文件路径
    pdf = pisa.pisaDocument(BytesIO(html.encode("UTF-8")), result, link_callback=link_callback)
    if not pdf.err:
        return result.getvalue()
    return None

2. 确保settings.py静态配置正确 #

检查settings.py中静态资源的配置，确保STATIC_URL和STATIC_ROOT（或STATICFILES_DIRS）配置正确：

STATIC_URL = '/static/'
# 生产环境静态文件收集目录
STATIC_ROOT = os.path.join(BASE_DIR, 'staticfiles')
# 开发环境静态文件源目录
STATICFILES_DIRS = [
    os.path.join(BASE_DIR, 'static'),
]

3. 开发环境注意事项 #

开发环境下需先运行python manage.py collectstatic，将静态文件收集到STATIC_ROOT目录，否则link_callback无法找到文件。

临时测试方案（不推荐用于生产） #

如果仅做临时测试，可直接在模板中使用图片的本地绝对路径替换{% static %}标签：

<img src="/your/project/absolute/path/static/images/tof.png" style="width:100px;height: 100px;">

此方法灵活性差，部署时路径变化会导致图片失效，优先使用第一种解决方案。

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