Django视图中使用Pisa将图片渲染为PDF时遇到的问题

嘿，我之前也碰到过一模一样的坑！这种情况90%都是因为PDF渲染引擎和浏览器对图片资源的处理逻辑不一样——浏览器能轻松解析的相对路径、动态Blob或者Data URI，PDF工具（比如wkhtmltopdf、Dompdf、WeasyPrint这类）经常“不认账”。下面是我踩过坑后总结的排查和解决步骤：

1. 先把图片路径换成绝对可访问的URL #

模板里如果用的是相对路径（比如/static/avatar.jpg），PDF渲染工具没办法像浏览器一样自动补全域名。你得换成完整的绝对URL，比如http://your-app-domain.com/static/avatar.jpg。

• 如果是本地开发，记得用http://localhost:8000/xxx这种格式，别用file:///本地文件路径——很多PDF引擎对本地文件的读取权限有限制。

2. 动态数据库图片别直接用Data URI（除非迫不得已） #

从数据库取的二进制图片，别直接在模板里输出data:image/jpeg;base64,...：

• 有些PDF引擎对Data URI的支持很差，尤其是大图片，容易导致渲染失败或者PDF体积暴增。
• 更稳妥的做法是：把二进制数据临时存到服务器的静态目录，生成一个临时可访问的URL传给模板；或者用后端代码直接把图片二进制注入到PDF中（不同工具的实现方式不同，比如WeasyPrint支持直接传入图片字节流）。

举个Python+WeasyPrint的例子：

# 从数据库取出图片二进制
from django.core.files.base import ContentFile
from myapp.models import UserAvatar
import base64

avatar = UserAvatar.objects.get(user_id=1).image_file
# 转换成Base64（如果一定要用Data URI的话）
base64_avatar = base64.b64encode(avatar.read()).decode('utf-8')
# 传给模板
context = {'avatar_base64': base64_avatar}

模板里对应写：

<img src="data:image/png;base64,{{ avatar_base64 }}" alt="User Avatar">

3. 检查PDF渲染工具的资源访问权限 #

• 如果用wkhtmltopdf，记得加上--allow /path/to/your/static/folder参数，允许它读取本地静态文件。
• 如果用Dompdf，要设置chroot选项限制它的资源访问范围，同时把你的图片目录加入允许列表：

$dompdf = new Dompdf();
$dompdf->set_option('chroot', realpath(__DIR__ . '/../public')); // 指向你的静态资源根目录

4. 验证图片的MIME类型和响应头 #

如果是通过接口返回图片，别忘记设置正确的Content-Type头（比如image/jpeg），并且加上Content-Disposition: inline——让PDF工具知道这是一张可直接渲染的图片，而不是需要下载的文件。

快速测试方法 #

你可以先把模板里的图片换成一个公开的在线图片（比如随便找个网络图片URL），如果能正常渲染到PDF里，那肯定是本地资源路径/权限的问题，照着上面的步骤调整就行！

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