
WeasyPrint 在 Flask 中生成 PDF 时无法显示图片,通常源于 img 标签的 src 路径未正确解析为相对于 base_url 的绝对路径,核心在于静态资源路径映射不匹配。
weasyprint 在 flask 中生成 pdf 时无法显示图片,通常源于 img 标签的 src 路径未正确解析为相对于 base_url 的绝对路径,核心在于静态资源路径映射不匹配。
在使用 WeasyPrint 将 HTML 字符串渲染为 PDF 时,所有外部资源(尤其是图片)的路径必须能被 WeasyPrint 根据 base_url 成功解析为本地文件系统中的可读路径。WeasyPrint 不会发起 HTTP 请求加载网络图片,也不支持 data: URL 或相对路径(如 ./images/logo.png),它仅依据 base_url 对 src 做路径拼接后尝试读取本地文件。
例如,若你的 Flask 应用静态文件夹为 app.static_folder = '/path/to/myapp/static',而 HTML 中有:
<img src="images/logo.png">
则 WeasyPrint 会尝试读取 /path/to/myapp/static/images/logo.png —— 这要求该路径真实存在且可读。
✅ 正确做法:
- 确保
base_url指向 Flask 的static_folder(而非 URL 路径如/static); - 所有
的值应为相对于static_folder的路径(即去掉/static前缀); - 若用 BeautifulSoup 动态插入图片,务必校验生成的
src属性是否符合上述规则:
# ✅ 正确:将原始 URL /static/images/chart.png → images/chart.png soup_img['src'] = 'images/chart.png' # 相对于 static_folder # ❌ 错误示例(会导致图片缺失) # soup_img['src'] = '/static/images/chart.png' # 绝对 URL,WeasyPrint 无法解析 # soup_img['src'] = 'https://example.com/logo.png' # 远程地址,不支持 # soup_img['src'] = './images/logo.png' # 相对路径,base_url 拼接后可能出错
⚠️ 额外注意事项:
- 图片文件需具有读取权限(尤其在 Linux/macOS 部署时);
- 支持格式为 PNG、JPEG、GIF、SVG(内联 SVG 可直接嵌入 HTML);
- 推荐在
convert_html_to_pdf中添加路径调试日志,验证实际解析路径:from pathlib import Path resolved_path = Path(base_url) / 'images/logo.png' print("Resolved image path:", resolved_path, "exists?", resolved_path.exists()) - 如需动态生成图片(如 Matplotlib 图表),建议先保存至
static/下临时子目录,再以相对路径引用。
总结:WeasyPrint 的图片加载本质是本地文件系统访问,不是浏览器渲染。只要确保 base_url + img[src] 构成合法、可读的绝对路径,并在 HTML 构建阶段(如 BeautifulSoup 处理环节)严格遵循该逻辑,即可稳定输出含图 PDF。










