如何在使用Headless Chrome生成PDF时添加带页码的自定义页脚

核心逻辑 #

Headless Chrome原生支持通过参数配置页眉页脚，结合Laravel常用的工具包（如spatie/browsershot）即可实现带页码的自定义页脚，关键是启用页眉页脚显示并传入自定义HTML模板。

1. 关键参数说明 #

必须开启displayHeaderFooter参数，通过footerTemplate传入自定义HTML模板，同时需给页面底部设置足够边距避免内容覆盖页脚。模板支持以下内置占位符：

• {pageNumber}：当前页码
• {totalPages}：总页数
• {date}：当前日期
• {time}：当前时间

2. Laravel中用Browsershot实现（推荐） #

多数Laravel项目会借助spatie/browsershot包调用Headless Chrome，以下是完整代码示例：

use Spatie\Browsershot\Browsershot;

// 从HTML字符串生成PDF
$pdf = Browsershot::loadHtml('<html><body>你的PDF内容主体</body></html>')
    // 启用页眉页脚显示
    ->setOption('displayHeaderFooter', true)
    // 自定义页脚模板，支持内联CSS
    ->setOption('footerTemplate', '<div style="font-size:10px; font-family:微软雅黑; text-align:center; width:100%; padding:5px; color:#666;">第 {pageNumber} 页 / 共 {totalPages} 页</div>')
    // 给页脚预留20mm底部边距
    ->setOption('marginBottom', '20mm')
    // 保存到指定路径
    ->save(storage_path('app/public/output.pdf'));

// 直接返回给浏览器下载
return response()->download(storage_path('app/public/output.pdf'));

3. 复杂页脚布局示例 #

如果需要分栏显示多类信息（如公司名称、页码、日期），可扩展模板：

->setOption('footerTemplate', '
    <div style="font-size:10px; font-family:Arial; width:90%; margin:0 auto; display:flex; justify-content:space-between; color:#333;">
        <span>XX科技有限公司</span>
        <span>第 {pageNumber} 页 / 共 {totalPages} 页</span>
        <span>{date}</span>
    </div>
')

4. 直接调用Chrome命令行（无工具包场景） #

若项目未使用工具包，可直接执行Chrome命令：

chrome --headless --disable-gpu --print-to-pdf="/path/to/output.pdf" \
--display-header-footer \
--footer-template="<div style='text-align:center; font-size:10px;'>第 {pageNumber} 页，共 {totalPages} 页</div>" \
--margin-bottom=20mm \
"/path/to/input.html"

常见问题排查 #

• 页脚不显示：检查是否开启displayHeaderFooter，确认marginBottom设置足够，模板HTML标签是否闭合
• 样式失效：模板内必须使用内联CSS，无法引用外部样式表
• 占位符无效：确保占位符名称拼写正确（区分大小写）

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