# @browserless/pdf 中文文档

规范地址：https://npmcn.com/package/%40browserless/pdf/

版本：14\.1\.6
npm 元数据更新时间：2026-11-07T09:49:44.302Z
中文译文更新时间：2026-11-08T16:27:38.504Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40browserless/pdf
原文对照：https://npmcn.com/package/%40browserless/pdf/?lang=original
项目主页：https://browserless.js.org/#/?id=pdfurl-options
源码仓库：https://github.com/microlinkhq/browserless#master

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：14.2 kB，4 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>= 24
- 运行依赖：6 个
- 首次发布：2019-03-10T19:11:22.708Z
- 最新版本发布：2026-11-07T09:49:44.127Z
- 近 30 天下载量：23184（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：426（近 12 个月 107 个）

## 中文简介

将网站转换为高质量的PDF,具有自定义的边距,背景打印,并优化了缩放.

## 安装

```sh
npm install @browserless/pdf
```

也可以使用：`pnpm add @browserless/pdf`、`yarn add @browserless/pdf`、`bun add @browserless/pdf`

## README

![browserless](https://github.com/microlinkhq/browserless/raw/master/static/logo-banner.png#gh-light-mode-only) ![browserless](https://github.com/microlinkhq/browserless/raw/master/static/logo-banner-light.png#gh-dark-mode-only)  
  
[![Powered by microlink.io](https://img.shields.io/badge/powered_by-microlink.io-blue?style=flat-square&color=%23EA407B)](https://microlink.io/) ![Last version](https://img.shields.io/github/tag/microlinkhq/browserless.svg?style=flat-square) [![Coverage Status](https://img.shields.io/coveralls/microlinkhq/browserless.svg?style=flat-square)](https://coveralls.io/github/microlinkhq/browserless) [![NPM Status](https://img.shields.io/npm/dm/browserless.svg?style=flat-square)](https://www.npmjs.org/package/browserless)  
  

> @browserless/pdf:将一个网站导出为PDF的感知好默认.

见 [pdf 节](https://browserless.js.org/#/?id=pdfurl-options) 我们的网站有更多信息.

## 安装

使用 npm :

```sh
npm install @browserless/pdf --save
```

## 关于

此软件包提供 **PDF 生成** 从网页上读取有合理默认和智能内容检测。 它包着普普提特的 `page.pdf()` 具有优化设置和重试机制,以确保在生成 PDF 之前充分提供页面.

### 这个软件包做什么

这个 `@browserless/pdf` 软件包允许您 :

-   **生成 PDF** 从任何含有生产准备默认值的 URL
-   **等页面准备好** 包括空白屏幕检查
-   **自定义边距** 带有简单字符串或平面配置
-   **缩放内容** 以最佳方式匹配页面
-   **使用所有的 PPDF 选项** 高级定制

### 使用量

```js
const createPdf = require('@browserless/pdf')
const createGoto = require('@browserless/goto')

const goto = createGoto({ timeout: 30000 })
const pdf = createPdf({ goto })

// With browserless
const browserless = await browser.createContext()
const pdfBuffer = await browserless.pdf('https://example.com')

// Or directly with a page
const page = await browser.newPage()
const pdfFn = pdf(page)
const pdfBuffer = await pdfFn('https://example.com')
```

### 默认设置

软件包应用这些优化的默认值 :

| 选项 | 默认 | 说明 |
| --- | --- | --- |
| `margin` | `'0.35cm'` | 页边距(适用于所有方) |
| `scale` | `0.65` | 最佳匹配的内容尺度因素 |
| `printBackground` | `true` | 包含背景颜色/图像 |
| `waitUntil` | `'auto'` | 智能等待和内容检测 |

### 选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `margin` | `string | object` | `'0.35cm'` | 页面边距 |
| `scale` | `number` | `0.65` | 网页渲染的规模(0.1-2) |
| `printBackground` | `boolean` | `true` | 打印背景图形 |
| `waitUntil` | `string` | `'auto'` | 何时考虑导航完成 |
| `format` | `string` | `'Letter'` | 纸张格式 (A4, 字母等) |
| `landscape` | `boolean` | `false` | 纸张取向 |
| `width` | `string | number` | —— 说 | 纸张宽度( 覆盖格式) |
| `height` | `string | number` | —— 说 | 纸张高度( 覆盖格式) |
| `pageRanges` | `string` | —— 说 | 打印的纸张范围,例如“ 1-5, 8” |
| `headerTemplate` | `string` | —— 说 | HTML 页眉模板 |
| `footerTemplate` | `string` | —— 说 | 页脚的 HTML 模板 |
| `displayHeaderFooter` | `boolean` | `false` | 显示页眉和页脚 |
| `preferCSSPageSize` | `boolean` | `false` | 优先使用 CSS @ page 大小 |

全体 [Puppeteer page.pdf () 选项](https://pptr.dev/api/puppeteer.pdfoptions) 被支持.

### 边距配置

设置边值为单值(适用于所有方)或平面:

```js
// Single value for all sides
await browserless.pdf(url, { margin: '1cm' })

// Per-side configuration
await browserless.pdf(url, {
  margin: {
    top: '2cm',
    right: '1cm',
    bottom: '2cm',
    left: '1cm'
  }
})
```

支助单位: `px`, (中文(简体) ), `in`, (中文(简体) ), `cm`, (中文(简体) ), `mm`

### 智能内容检测

何时 `waitUntil: 'auto'` (默认),包:

1.  导航到页面
2.  等待油漆/准备状态信号(`waitForReady` + 键 `isPageReady`(中文(简体) )
3.  水合物溢出后,一旦准备好(`prepareFullDocument`(中文(简体) )
4.  生成 PDF

这保证了动态内容(JavaScript-resisted pages)在PDF生成前被完全加载.

```js
// Use auto detection (default)
await browserless.pdf(url, { waitUntil: 'auto' })

// Or use standard Puppeteer wait conditions
await browserless.pdf(url, { waitUntil: 'networkidle0' })
await browserless.pdf(url, { waitUntil: 'domcontentloaded' })
```

### 实例

#### 基本 PDF 生成

```js
const pdfBuffer = await browserless.pdf('https://example.com')
await fs.writeFile('output.pdf', pdfBuffer)
```

#### 有自定义边距的 A4 格式

```js
const pdfBuffer = await browserless.pdf('https://example.com', {
  format: 'A4',
  margin: '2cm',
  scale: 0.8
})
```

#### 有页眉/页脚的景观

```js
const pdfBuffer = await browserless.pdf('https://example.com', {
  landscape: true,
  displayHeaderFooter: true,
  headerTemplate: '<div style="font-size:10px; text-align:center; width:100%;">Header</div>',
  footerTemplate: '<div style="font-size:10px; text-align:center; width:100%;"><span class="pageNumber"></span>/<span class="totalPages"></span></div>'
})
```

#### 打印特定页面

```js
const pdfBuffer = await browserless.pdf('https://example.com', {
  pageRanges: '1-3, 5'
})
```

### 如何适合在单体

这是一个 **核心功能软件包** 用于 PDF 生成 :

| 消费者 | 目的 |
| --- | --- |
| `browserless` (核心数) | 规定 `.pdf()` 方法 |
| `@browserless/cli` | 权力 `browserless pdf` 命令 |

### 依赖关系

| 软件包 | 目的 |
| --- | --- |
| `@browserless/goto` | 用广告屏蔽的页面导航 |
| `@browserless/screenshot` | 准备状态和空白屏幕检查 |
| `@kikobeats/time-span` | 重试逻辑的时间测量 |
| `debug-logfmt` | 结构化调试日志 |
| `pretty-ms` | 人类可读时间格式化 |

## 许可证

**@ 浏览器不可用/ pdf** © [微链接](https://microlink.io/),在 [麻省理工学院](https://github.com/microlinkhq/browserless/blob/master/LICENSE.md) 执照.  
作者和维护者 [微链接](https://microlink.io/) 由来自 [捐助者](https://github.com/microlinkhq/browserless/contributors)。 。 。 .

这个 [标志](https://thenounproject.com/term/browser/288309/) 设计由 [辛赫工作室](https://xinh.studio/)。 。 。 .

> [微链接.io](https://microlink.io/) • GitHub 软件 [微链克](https://github.com/microlinkhq) • X [@microlinkhq (英语)](https://x.com/microlinkhq)

## 常见问题

### @browserless/pdf 是什么？

将网站转换为高质量的PDF,具有自定义的边距,背景打印,并优化了缩放\.

### 如何安装 @browserless/pdf？

在项目目录运行 npm install @browserless/pdf，或使用 pnpm add / yarn add / bun add。

### @browserless/pdf 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/browserless\_\_pdf 是否存在。

### @browserless/pdf 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @browserless/pdf 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>= 24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @browserless/pdf 可以商用吗？

@browserless/pdf 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @browserless/pdf 的下载量有多少？

根据 npm 官方下载统计，@browserless/pdf 在 2026/10/09 – 2026/11/07 这 30 天内被下载 23,184 次，日均约 773 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @browserless/pdf 还在维护吗？

最新版本 14\.1\.6 发布于 2026/11/07（1 天前）；至今共发布 426 个版本，其中过去 12 个月发布了 107 个；首次发布于 2019/03/11。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。