# @browserless/screenshot 中文文档

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

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

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

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

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

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

## 中文简介

抓取具有覆盖支持,设备仿真,图像自动优化的网站高品质截图.

## 安装

```sh
npm install @browserless/screenshot
```

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

## 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)  
  

> @browserles/截图:拿一个干净的截图任何网站.

见 [截图区域](https://browserless.js.org/#/?id=screenshoturl-options) 我们的网站有更多信息.

## 安装

使用 npm :

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

## 关于

此软件包提供 **高级截图抓取** 带有智能默认,浏览器框架覆盖,梯度背景,以及自动代码语法突出. 它包着傀儡的 `page.screenshot()` 具有优化生产用途的特征.

### 这个软件包做什么

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

-   **抓取截图** 有设备模拟和智能等待
-   **添加浏览器框架覆盖** (暗地或淡地主题)
-   **应用梯度或图像背景** 为社交媒体准备的图像
-   **自动检测空白截图** 重试,直到内容完成
-   **语法高亮代码** (JSON,文本)与Prism.js主题
-   **获取特定要素** 使用 CSS 选择器
-   **全页截图** 有懒惰内容支持

### 使用量

```js
const createScreenshot = require('@browserless/screenshot')
const createGoto = require('@browserless/goto')

const goto = createGoto({ timeout: 30000 })
const screenshot = createScreenshot({ goto })

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

// With overlay
const buffer = await browserless.screenshot('https://example.com', {
  overlay: {
    browser: 'dark',
    background: 'linear-gradient(45deg, #FF057C 0%, #8D0B93 50%, #321575 100%)'
  }
})
```

### 选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `type` | `string` | `'png'` | 图像格式 : `'png'`, (中文(简体) ), `'jpeg'`, (中文(简体) ), `'webp'` |
| `quality` | `number` | —— 说 | JPEG/WebP 的质量( 0- 100) |
| `fullPage` | `boolean` | `false` | 抓取完整可滚动页面 |
| `element` | `string` | —— 说 | 元素截图的 CSS 选择器 |
| `codeScheme` | `string` | `'atom-dark'` | Prism.j 代码突出显示的主题 |
| `waitUntil` | `string` | `'auto'` | 何时考虑导航完成 |
| `isPageReady` | `function` | `({ isWhite }) => !isWhite` | 自定义重试循环的准备状态 |
| `overlay` | `object` | `{}` | 浏览器覆盖选项 |

全体 [Puppeteer 页面.screw() 选项](https://pptr.dev/api/puppeteer.screenshotoptions) 被支持.

### 浏览器重叠

在您截图上添加一个浏览器框架, 用于擦亮外观 :

```js
const buffer = await browserless.screenshot(url, {
  overlay: {
    // Browser frame theme: 'dark' or 'light'
    browser: 'dark',

    // Background: color, gradient, or image URL
    background: 'linear-gradient(225deg, #FF057C 0%, #8D0B93 50%, #321575 100%)',

    // Margin around the screenshot (default: 0.2 = 20%)
    margin: 0.2
  }
})
```

#### 背景选项

```js
// Solid color
overlay: { background: '#c1c1c1' }

// CSS gradient
overlay: { background: 'linear-gradient(45deg, #12c2e9, #c471ed, #f64f59)' }

// Image URL
overlay: { background: 'https://picsum.photos/1920/1080' }
```

### 元素截图

捕获特定的 DOM 元素 :

```js
const buffer = await browserless.screenshot(url, {
  element: '.hero-section'
})

// The package waits for the element to be visible
const buffer = await browserless.screenshot(url, {
  element: '#main-content'
})
```

### 全页截图

用懒惰内容抓取整个可滚动页面 :

```js
const buffer = await browserless.screenshot(url, {
  fullPage: true
})
```

软件包自动 :

1.  等待DOM稳定
2.  通过页面滚动来触发懒惰的图像
3.  向上滚动
4.  拿着截图

### 代码语法突出显示

当反应是JSON或纯文本时,包会自动地用语法突出显示:

```js
// Screenshot of a JSON API response
const buffer = await browserless.screenshot('https://api.example.com/data', {
  codeScheme: 'atom-dark'  // or any Prism.js theme
})
```

可用主题来自 [自动马德-棱镜主题](https://github.com/automadcms/automad-prism-themes) 财务报告和审定财务报表 [棱镜主题](https://github.com/PrismJS/prism-themes)。当两者中都存在一个主题时,则使用自动调试版本.

| 主题 | 来源 |
| --- | --- |
| `a11y-dark` | 棱镜主题 |
| `atom-dark` | 自定义 |
| `atom-one-dark` | 自定义 |
| `atom-one-light` | 自定义 |
| `aura-dark` | 自定义 |
| `automad-dark` | 自定义 |
| `automad-light` | 自定义 |
| `ayu-dark` | 自定义 |
| `ayu-light` | 自定义 |
| `ayu-mirage` | 自定义 |
| `base` | 自定义 |
| `base16-ateliersulphurpool.light` | 棱镜主题 |
| `bearded-arc-blueberry` | 自定义 |
| `bearded-vivid-light` | 自定义 |
| `boola-dark` | 自定义 |
| `boola-light` | 自定义 |
| `catppuccin-frappe` | 自定义 |
| `catppuccin-latte` | 自定义 |
| `catppuccin-macchiato` | 自定义 |
| `catppuccin-mocha` | 自定义 |
| `cb` | 棱镜主题 |
| `coldark-cold` | 自定义 |
| `coldark-dark` | 自定义 |
| `coy-without-shadows` | 棱镜主题 |
| `darcula` | 棱镜主题 |
| `dark-frost` | 自定义 |
| `dark-space` | 自定义 |
| `dracula` | 自定义 |
| `duotone-dark` | 自定义 |
| `duotone-earth` | 自定义 |
| `duotone-forest` | 自定义 |
| `duotone-light` | 自定义 |
| `duotone-sea` | 自定义 |
| `duotone-space` | 自定义 |
| `ghcolors` | 棱镜主题 |
| `github-dark` | 自定义 |
| `github-light` | 自定义 |
| `gruvbox-dark` | 自定义 |
| `gruvbox-light` | 自定义 |
| `holi-theme` | 棱镜主题 |
| `hopscotch` | 棱镜主题 |
| `laserwave` | 自定义 |
| `lucario` | 棱镜主题 |
| `material-dark` | 棱镜主题 |
| `material-light` | 棱镜主题 |
| `material-oceanic` | 棱镜主题 |
| `night-owl` | 自定义 |
| `night-owl-light` | 自定义 |
| `nightfall` | 自定义 |
| `nord` | 自定义 |
| `one-dark` | 棱镜主题 |
| `one-light` | 棱镜主题 |
| `panda` | 自定义 |
| `poimandres` | 自定义 |
| `pojoaque` | 棱镜主题 |
| `rose-pine` | 自定义 |
| `rose-pine-dawn` | 自定义 |
| `sakura-sun` | 自定义 |
| `sea-shells-dark` | 自定义 |
| `serendipity-midnight` | 自定义 |
| `serendipity-morning` | 自定义 |
| `serendipity-sunset` | 自定义 |
| `shades-of-purple` | 自定义 |
| `solarized-dark-atom` | 自定义 |
| `synthwave84` | 自定义 |
| `tailwind-ice` | 自定义 |
| `tailwind-moon-blue` | 自定义 |
| `tokyo-night` | 自定义 |
| `tokyo-night-light` | 自定义 |
| `tokyo-night-storm` | 自定义 |
| `verdandi` | 自定义 |
| `verdandi-alter` | 自定义 |
| `violet-dream` | 自定义 |
| `vs` | 棱镜主题 |
| `vsc-dark-plus` | 自定义 |
| `xonokai` | 棱镜主题 |
| `z-touch` | 棱镜主题 |

一些主题还提供轻/暗组合变体,将两种模式都捆绑在一个单一的CSS文件中,根据页面的暗模式类自动切换. 由于截图在不暗模式上下文的情况下渲染出,光变体将永远被使用——更喜欢像 `github-light` 或者说 `github-dark` 换句话说.

可用组合主题 :

| 组合主题 | 光线 | 阴暗 |
| --- | --- | --- |
| `atom-one.light-dark` | `atom-one-light` | `atom-one-dark` |
| `automad.light-dark` | `automad-light` | `automad-dark` |
| `ayu.light-dark` | `ayu-light` | `ayu-dark` |
| `ayu-mirage.light-dark` | `ayu-light` | `ayu-mirage` |
| `bearded-arc-blueberry.light-dark` | `bearded-vivid-light` | `bearded-arc-blueberry` |
| `boola.light-dark` | `boola-light` | `boola-dark` |
| `catppuccin-frappe.light-dark` | `catppuccin-latte` | `catppuccin-frappe` |
| `catppuccin-macchiato.light-dark` | `catppuccin-latte` | `catppuccin-macchiato` |
| `catppuccin-mocha.light-dark` | `catppuccin-latte` | `catppuccin-mocha` |
| `coldark.light-dark` | `coldark-cold` | `coldark-dark` |
| `github.light-dark` | `github-light` | `github-dark` |
| `gruvbox.light-dark` | `gruvbox-light` | `gruvbox-dark` |
| `night-owl.light-dark` | `night-owl-light` | `night-owl` |
| `rose-pine.light-dark` | `rose-pine-dawn` | `rose-pine` |
| `serendipity-midnight.light-dark` | `serendipity-morning` | `serendipity-midnight` |
| `serendipity-sunset.light-dark` | `serendipity-morning` | `serendipity-sunset` |
| `tailwind-moon-blue.light-dark` | `tailwind-ice` | `tailwind-moon-blue` |
| `tokyo-night-storm.light-dark` | `tokyo-night-light` | `tokyo-night-storm` |
| `tokyo-night.light-dark` | `tokyo-night-light` | `tokyo-night` |
| `verdandi.light-dark` | `verdandi` | `verdandi-alter` |

### 智能内容检测

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

1.  导航到页面
2.  等待字体加载
3.  在视图端口等待图像解码
4.  取一个截图
5.  如果截图是空白/ 白色的, 请重复等待

这保证了JavaScript-landed内容被完全装入.

### 实例

#### 社交媒体卡

```js
const buffer = await browserless.screenshot('https://example.com', {
  device: 'iPhone 13',
  overlay: {
    browser: 'light',
    background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)'
  }
})
```

#### API 文档截图

```js
const buffer = await browserless.screenshot('https://api.example.com/docs', {
  fullPage: true,
  type: 'jpeg',
  quality: 85
})
```

#### 具体构成部分

```js
const buffer = await browserless.screenshot('https://example.com', {
  element: '[data-testid="pricing-table"]',
  type: 'png'
})
```

### 建筑

```
@browserless/screenshot
├── src/
│   ├── index.js            → Main screenshot logic with smart waiting
│   ├── is-white-screenshot.js → Blank screenshot detection using Jimp
│   ├── time-span.js        → Timing utility
│   ├── overlay/
│   │   ├── index.js        → Browser frame and background composition
│   │   ├── dark.png        → Dark browser frame
│   │   └── light.png       → Light browser frame
│   └── pretty/
│       ├── index.js        → Code content detection and rendering
│       ├── html.js         → HTML template for code display
│       ├── prism.js        → Prism.js syntax highlighter
│       └── theme.js        → Prism theme loader
└── test/
    └── index.js            → Tests
```

### 如何适合在单体

这是一个 **核心功能软件包** 用于截图抓取 :

| 消费者 | 目的 |
| --- | --- |
| `browserless` (核心数) | 规定 `.screenshot()` 方法 |
| `@browserless/cli` | 权力 `browserless screenshot` 命令 |
| `@browserless/pdf` | 用途 `waitForReady` 财务报告和审定财务报表 `isWhiteScreenshot` |

### 依赖关系

| 软件包 | 目的 |
| --- | --- |
| `@browserless/goto` | 用广告屏蔽的页面导航 |
| `sharp` | 覆盖图的图像组成; 白/空白截图检测 |
| `automad-prism-themes` | 语法突出突出主题 |
| `svg-gradient` | 生成梯度背景 |
| `got` | 获取远程背景图像 |
| `is-html-content` | 检测内容是否为 HTML 对代码 |

## 许可证

**@ browser/ 截图** © [微链接](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/screenshot 是什么？

抓取具有覆盖支持,设备仿真,图像自动优化的网站高品质截图\.

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

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

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

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

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

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

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

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

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

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

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

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

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

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