如何通过Chromium命令行自动将本地HTML文件转为PDF？

问题描述 #

需要在自动化场景下，用Chromium 145.0.7605.0+将本地my.html文件自动打印为PDF。尝试以下命令未生成PDF：

$ rm -rf tmp # 确保环境干净
$ chromium \
  --disable-web-security \
  --user-data-dir="${PWD}/tmp" \
  --print-to-pdf \
  --no-pdf-header-footer \
  --debug-print \
  --kiosk-printing \
  --headless \
  my.html

关闭--headless后，仅手动按CTRL+P才会弹出预览并保存PDF。尝试用wrapper.html通过iframe加载并JS触发打印，弹出预览后无法自动完成打印：

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Wrapper</title>
  <script>
    window.addEventListener("load", () => {
      const iframe = document.createElement("iframe");
      iframe.src = "my.html";
      iframe.onload = () => {
        iframe.focus();
        iframe.contentWindow.print();
      }
      document.body.appendChild(iframe);
    });
  </script>
  <style>
    body {
      margin:0px;
      padding:0px;
      overflow: hidden;
    }

    iframe {
      width: 100%;
      height: 100%;
      border: 0px solid black;
      position: absolute;
    }
  </style>
</head>
<body>
</body>
</html>

解决方案 #

1. 修正无头模式核心命令 #

Chromium 145+推荐使用新版无头模式，同时明确PDF输出路径，修正后的命令如下：

rm -rf tmp # 清理用户数据目录，避免缓存干扰
chromium \
  --headless=new \
  --disable-web-security \
  --user-data-dir="${PWD}/tmp" \
  --print-to-pdf="./output.pdf" \
  --no-pdf-header-footer \
  --kiosk-printing \
  "file://${PWD}/my.html"

关键调整点：

• 替换--headless为--headless=new：新版无头模式对打印流程的支持更稳定，解决旧版无头模式下的静默打印失效问题
• 明确--print-to-pdf的输出路径：默认不指定路径时，本地文件场景可能无法生成PDF文件
• 使用file://协议指定本地文件：避免Chromium对相对路径的解析异常

2. 优化Wrapper页面的自动打印逻辑 #

如果必须通过iframe加载页面，需调整JS逻辑等待内容渲染完成，并配合命令参数确保自动打印：
修改wrapper.html的脚本部分：

<script>
window.addEventListener("load", async () => {
  const iframe = document.createElement("iframe");
  iframe.src = "my.html";
  iframe.onload = async () => {
    // 等待iframe内容完全渲染（根据页面复杂度调整延迟时间）
    await new Promise(resolve => setTimeout(resolve, 500));
    iframe.contentWindow.focus();
    iframe.contentWindow.print();
    // 延迟关闭窗口，确保打印任务完成
    setTimeout(() => window.close(), 2000);
  };
  document.body.appendChild(iframe);
});
</script>

对应的执行命令：

chromium \
  --headless=new \
  --disable-web-security \
  --user-data-dir="${PWD}/tmp" \
  --kiosk-printing \
  --print-to-pdf="./output.pdf" \
  "file://${PWD}/wrapper.html"

3. 常见排查要点 #

• 版本验证：确认Chromium版本≥145.0.7605.0，低版本无头打印存在已知bug
• 权限检查：确保当前用户对PDF输出目录有读写权限
• 进程清理：执行命令前关闭所有Chromium进程，避免--user-data-dir被占用导致异常

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