wkhtmltopdf在Node.js/Express+Python应用中不渲染图片及页码问题

问题背景 #

在Node.js/Express应用中结合Python脚本使用wkhtmltopdf生成PDF时，出现以下问题：页眉、页脚HTML能正确嵌入文档，但HTML内容中的图片无法显示，页脚中的页码（<span class="page"></span>与<span class="topage"></span>）未被渲染。

正常工作项 #

• 页眉、页脚HTML文件已正确整合到PDF中
• 基础HTML内容渲染正常
• PDF文件可成功生成并保存

异常项 #

• HTML内容中的图片未在最终PDF中显示
• 页脚中的页码占位符未被替换为实际页码

配置信息 #

footer.html #

<div class="footer">
  <span class="left">© 2025 <a href="https://leanstack.me">leanstack.me</a> All rights reserved.</span>
  <span class="right">Page <span class="page"></span> of <span class="topage"></span></span>
</div>

header.html #

<div class="header">
  <img src="https://945f0bc1-1beb-46ba-b4ed-8b74bc579746-00-3tynn012wsw1z.janeway.replit.dev:5000/images/leanstack-main-logo.png" alt="Leanstack Logo">
</div>

Python PDF生成代码 #

class PDFGenerator:
    def __init__(self):
        self.config = pdfkit.configuration(wkhtmltopdf='/nix/store/n6zynih08kfi8dkkdpizmlq77j7kyk1i-wkhtmltopdf-bin-0.12.6-3/bin/wkhtmltopdf')
        self.options = {
            'quiet': '',
            'print-media-type': '',
            'page-size': 'Letter',
            'margin-top': '20mm',
            'margin-right': '20mm',
            'margin-bottom': '20mm',
            'margin-left': '20mm',
            'encoding': 'UTF-8'
        }

    def generate_pdf(self, html_content, output_path=None):
        # PDF generation code...

已尝试的解决方法 #

• 使用相对和绝对URL引用图片
• 通过命令行参数添加页眉页脚
• 确认图片可通过浏览器访问

解决方案 #

一、修复页码未渲染问题 #

wkhtmltopdf对页眉页脚中的页码变量替换需要明确指定页眉页脚文件路径，并配置间距避免内容覆盖，具体修改如下：

1. 更新options配置，添加页眉页脚文件路径及间距参数：

self.options = {
    'quiet': '',
    'print-media-type': '',
    'page-size': 'Letter',
    'margin-top': '20mm',
    'margin-right': '20mm',
    'margin-bottom': '20mm',
    'margin-left': '20mm',
    'encoding': 'UTF-8',
    'header-html': './header.html',  # 替换为实际文件路径
    'footer-html': './footer.html',  # 替换为实际文件路径
    'header-spacing': '5',  # 页眉与正文的间距（单位：mm）
    'footer-spacing': '5'   # 页脚与正文的间距（单位：mm）
}

2. 确保页眉页脚样式正确，避免页码元素被隐藏：
   在footer.html中添加基础样式，确保页码元素正常显示：

<style>
.footer { 
    width: 100%; 
    display: flex; 
    justify-content: space-between; 
    padding: 0 10mm; 
    font-size: 12px;
}
.page, .topage { 
    display: inline; 
    margin: 0 2px;
}
</style>
<div class="footer">
  <span class="left">© 2025 <a href="https://leanstack.me">leanstack.me</a> All rights reserved.</span>
  <span class="right">Page <span class="page"></span> of <span class="topage"></span></span>
</div>

二、修复图片不显示问题 #

结合Replit环境特性及wkhtmltopdf的网络访问限制，需添加以下配置：

1. 更新options配置，添加允许访问图片域名、图片加载相关参数：

self.options = {
    # 保留原有配置...
    'allow': 'https://945f0bc1-1beb-46ba-b4ed-8b74bc579746-00-3tynn012wsw1z.janeway.replit.dev',
    'no-images': False,
    'load-error-handling': 'ignore',
    'load-media-error-handling': 'ignore'
}

2. 验证网络访问权限：
   确认Replit项目已开启出站网络权限（默认开启，若有异常可在项目设置中检查），确保wkhtmltopdf能访问图片URL。

3. 检查图片路径：
   确保图片URL无拼写错误，且能在Replit环境中通过curl命令访问：

curl https://945f0bc1-1beb-46ba-b4ed-8b74bc579746-00-3tynn012wsw1z.janeway.replit.dev:5000/images/leanstack-main-logo.png

三、完整Python代码示例 #

import pdfkit

class PDFGenerator:
    def __init__(self):
        self.config = pdfkit.configuration(wkhtmltopdf='/nix/store/n6zynih08kfi8dkkdpizmlq77j7kyk1i-wkhtmltopdf-bin-0.12.6-3/bin/wkhtmltopdf')
        self.options = {
            'quiet': '',
            'print-media-type': '',
            'page-size': 'Letter',
            'margin-top': '20mm',
            'margin-right': '20mm',
            'margin-bottom': '20mm',
            'margin-left': '20mm',
            'encoding': 'UTF-8',
            'header-html': './header.html',
            'footer-html': './footer.html',
            'header-spacing': '5',
            'footer-spacing': '5',
            'allow': 'https://945f0bc1-1beb-46ba-b4ed-8b74bc579746-00-3tynn012wsw1z.janeway.replit.dev',
            'no-images': False,
            'load-error-handling': 'ignore',
            'load-media-error-handling': 'ignore'
        }

    def generate_pdf(self, html_content, output_path=None):
        try:
            if output_path:
                pdfkit.from_string(html_content, output_path, configuration=self.config, options=self.options)
                return output_path
            else:
                return pdfkit.from_string(html_content, False, configuration=self.config, options=self.options)
        except Exception as e:
            print(f"PDF生成错误: {str(e)}")
            return None

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