部署到Docker容器后Puppeteer生成PDF表头重叠问题

服务部署到Docker容器后，使用Puppeteer生成PDF时出现表头重叠问题——表格分页后第二页表头会覆盖第一页底部内容，但在Chrome浏览器中打开对应HTML并打印为PDF显示正常。已升级Node.js（20版本）和Puppeteer（v22版本），问题仍未解决，当前容器内Chrome版本为123.0.6312.122。以下是针对性的解决思路：

1. 统一容器与本地的字体环境 #

Docker容器内默认字体包可能不全，与本地Chrome字体差异会导致渲染布局偏移：

• 修改Dockerfile，添加更完整的字体包：

FROM node:20-alpine

RUN apk add --no-cache \
    chromium \
    nss \
    freetype \
    freetype-dev \
    harfbuzz \
    ca-certificates \
    ttf-freefont \
    ttf-dejavu \
    noto-fonts \
    fontconfig

RUN fc-cache -f -v

# 移除PUPPETEER_EXECUTABLE_PATH，改用Puppeteer内置Chrome（可选）
# ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser

WORKDIR /usr/src/app

COPY package*.json ./
COPY .npmrc ./

RUN npm install pm2 -g
RUN npm ci --only=production

COPY . .

EXPOSE 4042

CMD [ "pm2-runtime", "start", "/usr/src/app/process.yml" ]

• 确保HTML中使用的字体在容器内已安装，避免 fallback 字体触发布局变化。

2. 调整Puppeteer配置参数 #

优化启动参数 #

移除可能导致渲染异常的--no-zygote参数，使用新版无头模式：

const browser = await launch({
    headless: 'new', // 启用新版无头模式，渲染更接近常规Chrome
    args: [
        '--disable-features=IsolateOrigins',
        '--disable-site-isolation-trials',
        '--disable-dev-shm-usage',
        '--no-sandbox',
        '--disable-setuid-sandbox',
        '--ignore-gpu-blacklist',
        '--use-gl=swiftshader',
    ],
});

调整PDF生成流程 #

• 延迟emulateMediaType到页面内容加载完成后执行，确保样式正确应用：

await page.setContent(htmlString, { waitUntil: 'networkidle0' });
await page.emulateMediaType('print');
await page.evaluateHandle('document.fonts.ready');
await page.waitForTimeout(1000); // 增加等待时间确保字体和样式完全渲染

• 增大顶部边距，避免自定义页脚与页面内容冲突：

const pdfOptions = {
    displayHeaderFooter: true,
    preferCSSPageSize: true,
    format: 'A4',
    headerTemplate: '<div></div>',
    footerTemplate:
        "<div style=\"font-size:8px; text-align:end; width:100%; margin:0 10px;\"><span class='pageNumber'></span> / <span class='totalPages'></span></div>",
    margin: {
        top: '50px',
        bottom: '40px',
        left: '40px',
        right: '40px',
    },
};

3. 优化CSS打印样式 #

针对无头Chrome的渲染特性，强化打印样式规则，避免表头重叠：

@media print {
    /* 强制表头在每页重复显示 */
    thead {
        display: table-header-group !important;
    }
    /* 禁止表格行跨页拆分，避免内容被表头覆盖 */
    tr {
        page-break-inside: avoid !important;
    }
    /* 固定表格布局，防止宽度异常导致的重叠 */
    table {
        width: 100% !important;
        table-layout: fixed !important;
        border-collapse: collapse !important;
    }
    /* 确保表头有足够的内边距，避免与内容紧贴 */
    th {
        padding: 8px !important;
        white-space: nowrap !important;
    }
}

4. 验证浏览器版本兼容性 #

若以上方法无效，尝试切换Puppeteer使用的浏览器版本：

• 移除Dockerfile中系统级Chromium的安装，让Puppeteer自动下载匹配版本的Chrome，避免版本不兼容问题；
• 降级/升级Puppeteer版本，比如尝试v21或v23版本，排查是否为特定版本的渲染bug。

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