从wkhtmlpdf迁移至Gotenberg时PDF布局不一致问题求助

尝试从wkhtmlpdf迁移到Gotenberg生成PDF，但两者输出的PDF布局存在差异。已确保页面尺寸、边距等参数设置一致，怀疑问题出在Gotenberg的scale方法实现上。

配置代码对比 #

Gotenberg配置代码 #

$chromiumRequest = Gotenberg::chromium('http://gotenberg.kanbanbox.com:3000')->pdf()->assets(...$this->getFontAssets())
            ->margins(
                0.0 . 'mm',
                0.0 . 'mm',
                1.0 . 'mm',
                1.0 . 'mm',
            );

$chromiumRequest->scale($dimensionsTemplate->getZoom() ?? 0.5);

if ($dimensionsTemplate->getPageOrientation()->equals(Orientation::LANDSCAPE)) {
    $chromiumRequest->landscape();
}

$paperFormat = $dimensionsTemplate->getPageFormat();

if ($paperFormat === PaperFormat::HALF_LETTER) {
    $chromiumRequest->paperSize('140mm', '216mm');
} elseif ($paperFormat === PaperFormat::CUSTOM) {
    $pageHeight = $dimensionsTemplate->getPageHeight();
    $pageWidth  = $dimensionsTemplate->getPageWidth();
    if ($pageHeight !== null && $pageHeight > 0 && $pageWidth !== null && $pageWidth > 0) {
        $chromiumRequest->paperSize($pageWidth . 'mm', $pageHeight . 'mm');
    }
} else {
    $chromiumRequest->paperSize(PaperFormat::getDimensions($paperFormat)['width'] . 'mm', PaperFormat::getDimensions($paperFormat)['height'] . 'mm');
}

wkhtmlpdf配置代码 #

$commandLine =
                $commandName
                . ' --orientation ' . $dimensionsTemplate->getPageOrientation()->value
                . ' --zoom ' . 0.78 * ($dimensionsTemplate->getZoom() ?? 1.0)
                . ' --margin-top ' . $dimensionsTemplate->getMarginTop()
                . ' --margin-right ' . $dimensionsTemplate->getMarginRight()
                . ' --margin-bottom ' . $dimensionsTemplate->getMarginBottom()
                . ' --margin-left ' . $dimensionsTemplate->getMarginLeft();

$paperFormat = $dimensionsTemplate->getPageFormat();
if ($paperFormat === PaperFormat::HALF_LETTER) {
    //half letter是wkhtmlpdf不支持的格式，需手动指定宽高
    $commandLine .= ' --page-height 216 --page-width 140';
} elseif ($paperFormat === PaperFormat::CUSTOM) {
    $pageHeight = $dimensionsTemplate->getPageHeight();
    $pageWidth  = $dimensionsTemplate->getPageWidth();
    if ($pageHeight !== null && $pageHeight > 0 && $pageWidth !== null && $pageWidth > 0) {
        $commandLine .= ' --page-height ' . $pageHeight . ' --page-width ' . $pageWidth;
    }
} else {
    $commandLine .= ' --page-size ' . $paperFormat->value;
}

$commandLine .= ' --disable-smart-shrinking'
    . $webArgument[$i]
    . ' ' . $tmpPdfChunkName[$i]
    . ' 2>&1'; // 输出到STDOUT

布局对比 #

使用同一HTML文件生成的PDF对比：绿色为wkhtmlpdf输出，红色为Gotenberg输出

问题分析与解决建议 #

1. 对齐缩放逻辑
   wkhtmlpdf的--zoom额外乘以了0.78系数，且默认缩放值为1.0；而Gotenberg的scale默认值是0.5，两者缩放计算逻辑完全不同。尝试将Gotenberg的缩放代码改为：

   $chromiumRequest->scale(0.78 * ($dimensionsTemplate->getZoom() ?? 1.0));
   

2. 禁用自动缩放行为
   wkhtmlpdf用--disable-smart-shrinking禁止内容自动调整，Gotenberg默认可能存在类似机制。添加以下代码强制使用屏幕渲染模式，避免打印模式的自动调整：

   $chromiumRequest->emulatedMediaType('screen');
   

3. 确认页面尺寸单位一致性
   检查wkhtmlpdf中页面尺寸参数的默认单位（比如--page-height 216是否为mm），确保和Gotenberg的单位完全一致，避免单位解析差异导致布局偏差。

4. 统一字体渲染样式
   Chromium和wkhtmlpdf的字体渲染引擎不同，可能导致文字大小、行高细微差异。在HTML中明确指定font-size、line-height等样式，减少引擎差异的影响。

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