html-to-pdf

HTML 转 PDF 转换器

使用 Puppeteer（Chrome 无头模式）实现像素级精准的 HTML 转 PDF 转换。对希伯来语、阿拉伯语和其他 RTL 语言提供出色支持，并自动检测方向。

为什么选择 Puppeteer？

• 像素级精准渲染：使用真正的 Chrome 引擎
• 全面支持 CSS3/HTML5：Flexbox、Grid、自定义字体、背景
• 执行 JavaScript：渲染动态内容
• 自动检测 RTL：检测希伯来语/阿拉伯语并设置方向
• 支持 Web 字体：正确加载自定义字体

自动适配（内置，无需标志）

脚本会自动处理内容溢出：

• 轻微溢出（最多约 18%） → 自动缩小字体以适配页面
• 内容较多 → 按合理的分页规则流畅地跨多页排版（不会将标题、表格行或图片截成两半）
• 恰好适配 → 不做任何处理

每次生成 PDF 时都会自动执行，无需任何标志。

重要：将内容适配到单页

在 html 或 body 上设置背景会导致多出页面！ 请改为在容器元素上设置背景：

@page { size: A4; margin: 0; }

html, body {
  width: 210mm;
  height: 297mm;
  margin: 0;
  padding: 0;
  overflow: hidden;
  /* NO background here! */
}

.container {
  width: 100%;
  height: 100%;
  padding: 20mm;
  box-sizing: border-box;
  background: linear-gradient(...); /* Background goes HERE */
}

导致多出页面的常见原因：

1. 在 html/body 上设置背景——请始终改为在 .container 上设置
2. 内容溢出——使用 overflow: hidden
3. 外边距/内边距将内容挤出页面

提示：

• 如果内容仍然溢出，请使用 --scale=0.75 --margin=0
• 横向排版请使用 --landscape

安装（一次性）

首次使用前，请安装依赖项：

cd ~/.claude/skills/html-to-pdf && npm install

快速使用

转换本地 HTML 文件：

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js input.html output.pdf

将 URL 转换为 PDF：

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js https://example.com page.pdf

强制使用 RTL 的希伯来语文档：

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js hebrew.html hebrew.pdf --rtl

通过管道传入 HTML 内容：

echo "<h1>שלום עולם</h1>" | node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js - output.pdf --rtl

选项参考

选项	说明	默认值
--format=<format>	页面格式：A4、Letter、Legal、A3、A5	A4
--landscape	使用横向排版	false
--margin=<value>	设置所有边距（例如 "20mm"、"1in"）	20mm
--margin-top=<value>	上边距	20mm
--margin-right=<value>	右边距	20mm
--margin-bottom=<value>	下边距	20mm
--margin-left=<value>	左边距	20mm
--scale=<number>	缩放比例 0.1-2.0	1
--background	打印背景图形	true
--no-background	不打印背景	-
--header=<html>	页眉 HTML 模板	-
--footer=<html>	页脚 HTML 模板	-
--wait=<ms>	等待字体/JS 的时间	1000
--rtl	强制使用 RTL 方向	自动检测
--expect-pages=<N>	预期页数（不同时会发出警告）	1
--no-page-check	禁用页数警告	-

自动检测溢出

脚本会在生成 PDF 后自动检查页数。默认预期为 1 页，如果输出超过 1 页则会发出警告：

⚠️  WARNING: PAGE OVERFLOW DETECTED!
   Expected: 1 page(s)
   Actual:   2 page(s)

   Fix: Reduce content, margins, or font sizes in HTML
   Use --no-page-check to disable this warning

用法：

• 默认：预期为 1 页，溢出时发出警告
• --expect-pages=3：预期为 3 页（适用于多页文档）
• --no-page-check：完全禁用检查

注意： 需要安装 pdfinfo（属于 poppler-utils）。如果不可用，则会静默跳过检查。

示例

基本转换：

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js report.html report.pdf

使用自定义边距的 Letter 格式：

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js doc.html doc.pdf --format=Letter --margin=1in

希伯来语发票：

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js invoice-he.html invoice.pdf --rtl

横向演示文稿：

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js slides.html slides.pdf --landscape --format=A4

无边距（满版出血）：

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js poster.html poster.pdf --margin=0

希伯来语/RTL 最佳实践

要在 HTML 中获得最佳的希伯来语渲染效果：

1. 设置 lang 属性：<html lang="he" dir="rtl">
2. 使用 UTF-8：<meta charset="UTF-8">
3. CSS 方向：为 body 添加 direction: rtl; text-align: right;
4. 字体：使用支持希伯来语的 Web 字体（Noto Sans Hebrew、Heebo、Assistant）

希伯来语 HTML 结构示例（单页）：

<!DOCTYPE html>
<html lang="he" dir="rtl">
<head>
  <meta charset="UTF-8">
  <link href="https://fonts.googleapis.com/css2?family=Heebo:wght@400;700&display=swap" rel="stylesheet">
  <style>
    @page { size: A4; margin: 0; }
    html, body {
      width: 210mm;
      height: 297mm;
      margin: 0;
      padding: 0;
      overflow: hidden;
    }
    .container {
      width: 100%;
      height: 100%;
      padding: 20mm;
      box-sizing: border-box;
      font-family: 'Heebo', sans-serif;
      direction: rtl;
      text-align: right;
      background: #f5f5f5; /* Background on container, NOT body */
    }
  </style>
</head>
<body>
  <div class="container">
    <h1>שלום עולם</h1>
    <p>זהו מסמך בעברית</p>
  </div>
</body>
</html>

重要：多页 PDF 始终使用 scale=1.0

多页文档绝不要使用小于 1.0 的 --scale。 这会导致：

• 内容偏移（未在页面上居中）
• RTL 文本在网格布局中溢出或被裁切
• 视口宽度计算不可预测

应改为缩小 CSS 字体大小和间距，让内容适配 scale=1.0。

.page {
  width: 210mm;         /* Matches A4 exactly at scale=1.0 */
  height: 297mm;        /* Matches A4 exactly at scale=1.0 */
  padding: 8mm 10mm 12mm;
  page-break-after: always;
  position: relative;
  background: #f7f8fa;
  overflow: hidden;
  box-sizing: border-box;
}

**如果内容在 scale=1.0 时溢出：**缩小字体（基础字号设为 10-11px）、内边距和外边距，而不是缩放比例。这样可以保持 CSS 与 PDF 之间 1:1 的映射，消除所有布局异常。

**颜色提示：**纯白（#fff）背景会使彩色点缀显得黯淡。使用 #f7f8fa 或 #f8fafb，营造微妙的对比，让颜色更加醒目。

故障排除

字体渲染不正确

• 添加 --wait=2000，为字体加载留出更多时间
• 确保通过 @font-face 或 Google Fonts 加载字体

希伯来语显示为从左向右

• 使用 --rtl 标志强制 RTL 方向
• 在 HTML 元素中添加 dir="rtl"

分页不起作用

使用 CSS 分页属性：

.page-break { page-break-after: always; }
.no-break { page-break-inside: avoid; }

背景未显示

• 确保已设置 --background（默认为 true）
• 仅在要排除背景时使用 --no-background

内容自动适配（必须验证）

重要——Claude 必须在每次生成 PDF 后执行以下操作：

1. 使用 Read 工具读取 PDF 文件并进行目视检查
2. 检查是否有垂直溢出（空白页面、内容溢出到下一页）
3. 检查是否有水平溢出（文本被页面两侧裁切）
4. 如果发现任何问题 → 修复并重新生成（最多 5 次尝试）
5. 只有通过验证后，才能向用户交付 PDF

这不是可选项。未经目视验证，绝不要交付 PDF。

需要检查的问题

问题	表现	修复方法
垂直溢出	页面底部有空白，内容出现在下一页	缩小 --scale
水平裁切	文本在左侧或右侧被裁切	缩小 --margin 并修正 HTML 宽度
两者都有	内容被裁切且出现额外页面	先修正 HTML CSS，再调整缩放比例

修复策略（最多尝试 5 次）

**尝试 1：**使用默认设置

node scripts/html-to-pdf.js input.html output.pdf

**尝试 2：**如果有垂直溢出 → 缩小缩放比例

node scripts/html-to-pdf.js input.html output.pdf --scale=0.9

**尝试 3：**如果有水平裁切 → 缩小边距

node scripts/html-to-pdf.js input.html output.pdf --scale=0.9 --margin=10mm

**尝试 4：**如果问题仍然存在 → 进一步缩小缩放比例和边距

node scripts/html-to-pdf.js input.html output.pdf --scale=0.8 --margin=5mm

**尝试 5：**如果问题仍然存在 → 修复 HTML CSS：

/* Add to HTML to prevent horizontal overflow */
.container {
  width: 100%;
  max-width: 100%;
  overflow-wrap: break-word;
  word-wrap: break-word;
  box-sizing: border-box;
}

尝试 5 次后停止——使用适当的约束重新生成 HTML。

HTML 宽度修正（水平适配必需）

如果内容在页面两侧被裁切，HTML 必须包含：

html, body {
  width: 210mm;  /* A4 width */
  margin: 0;
  padding: 0;
  overflow: hidden;
}

.container {
  width: 100%;
  max-width: 100%;
  padding: 15mm;
  box-sizing: border-box;
  overflow-wrap: break-word;
}

验证清单

每次生成 PDF 后，都要验证：

• 所有文本均可见（页面边缘处未被裁切）
• 没有不必要的空白页面
• 内容恰当地填充页面
• 各部分之间没有过大的空隙

如果任何一项检查未通过 → 调整并重新生成（最多 5 次）。

技术说明

• 使用 Puppeteer 和无头 Chrome 进行渲染
• 等待 networkidle0，确保所有资源均已加载
• 自动等待 document.fonts.ready
• 支持用于打印样式的 @page CSS 规则
• 设备缩放因子设为 2，以实现清晰渲染