# @browserless/goto 中文文档

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

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

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

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

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

- 包体积（解压后）：9 MB，12 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>= 24
- 运行依赖：10 个
- peer 依赖：puppeteer 25
- 首次发布：2019-01-27T18:05:49.865Z
- 最新版本发布：2026-11-07T09:49:22.349Z
- 近 30 天下载量：24713（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：394（近 12 个月 95 个）

## 中文简介

导航到网页时带有内置的ad屏蔽,设备仿真,并优化加载,以加快自动化.

## 安装

```sh
npm install @browserless/goto
```

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

## 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/goto: 转到一个页面中止不必要的请求 .

见 [转到区域](https://browserless.js.org/#/?id=gotopage-options) 详情请见我们的网站.

## 安装

使用 npm :

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

## 关于

此软件包提供 **高级页面导航** 内置广告屏蔽 智能等待策略 以及广泛的定制选项 它是所有无浏览器页面加载操作的核心导航引擎.

### 这个软件包做什么

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

-   **导航到页面** 具有优化装载和智能等待策略
-   **块状广告和跟踪器** 使用预编成的 Ghostery 广告屏蔽引擎
-   **注入脚本、模块和样式** 输入页面
-   **模拟设备** 带有视图、用户代理和媒体特性
-   **拦截和中止请求** 按资源类型
-   **处理 cookie 和 HTTP 认证**

### 使用量

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

const goto = createGoto({ 
  timeout: 30000,
  defaultDevice: 'Macbook Pro 13'
})

const browser = await puppeteer.launch()
const page = await browser.newPage()

const { response, device, error } = await goto(page, {
  url: 'https://example.com',
  adblock: true,
  waitUntil: 'auto'
})
```

### 选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `url` | `string` | —— 说 | 要导航的目标 URL |
| `html` | `string` | —— 说 | 要渲染的 HTML 内容( 代替 URL) |
| `adblock` | `boolean` | `true` | 启用内置广告屏蔽器 |
| `waitUntil` | `string|string[]` | `'auto'` | 导航等待条件 |
| `timeout` | `number` | `30000` | 导航超时( ms) |
| `device` | `string` | `'Macbook Pro 13'` | 仿真设备;一个桌面设备提供取景口,而用户代理商内部的平台符号遵循主机OS |
| `headers` | `object` | `{}` | 额外的 HTTP 信头 |
| `javascript` | `boolean` | `true` | 启用/ 禁用 JavaScript |
| `notifications` | `boolean` | `false` | 允许立即允许通知 |
| `animations` | `boolean` | `false` | 启用 CSS 动画 |
| `colorScheme` | `string` | —— 说 | `'light'` 或者说 `'dark'` 偏好 |
| `flattenShadowDOM` | `boolean` | `false` (单位:千美元)`true` 页:1 `html()`(中文(简体) ) | 将打开的阴影 DOM 序列化为 HTML( 将页面 DOM; 关闭的阴影根跳过) |
| `mediaType` | `string` | —— 说 | CSS 媒体类型(`'screen'`, (中文(简体) ), `'print'`(中文(简体) ) |
| `timezone` | `string` | —— 说 | 要模拟的时区 |
| `authenticate` | `object` | —— 说 | HTTP 认证证书 |
| `scripts` | `string|string[]` | —— 说 | 要注入的脚本 |
| `modules` | `string|string[]` | —— 说 | 要注入的ES 模块 |
| `styles` | `string|string[]` | —— 说 | 要注入的样式表 |
| `click` | `string|string[]` | —— 说 | 单击 CSS 选择器 |
| `scroll` | `string` | —— 说 | 要滚动到视图的 CSS 选择器 |
| `abortTypes` | `string[]` | `[]` | 要中止的资源类型 |
| `waitForSelector` | `string` | —— 说 | 等待选择者出现 |
| `waitForFunction` | `string` | —— 说 | 等待函数返回真伪 |
| `waitForTimeout` | `number` | —— 说 | 等待指定的毫秒 |
| `onPageRequest` | `function` | —— 说 | 请求截取处理器 |

### 聪明的等待 `waitUntil: 'auto'`

默认 `'auto'` 模式 智能等待页面准备 :

```js
// Auto mode combines 'load' with 'networkidle2' smartly
await goto(page, { url: 'https://example.com', waitUntil: 'auto' })

// Standard Puppeteer wait conditions also supported
await goto(page, { url: 'https://example.com', waitUntil: 'networkidle0' })
await goto(page, { url: 'https://example.com', waitUntil: ['load', 'domcontentloaded'] })
```

### 内建的Ad 屏蔽器

包包括一个预编译 [幽灵广告屏蔽器](https://github.com/ghostery/adblocker) 自动屏蔽广告和跟踪器的引擎:

```js
// Enabled by default
await goto(page, { url: 'https://example.com', adblock: true })

// Disable for specific pages
await goto(page, { url: 'https://example.com', adblock: false })

// The adblocker can be disabled mid-session
page.disableAdblock()
```

Cookie 同意处理(选择退出)列为 `adblock: true` 和动力 [duckuckgo/自动同意](https://github.com/duckduckgo/autoconsent)。 。 。 .

`adblock: true` 也排除了非自动同意的通用公告对话框: ARIA 对话框(`role="dialog"`, (中文(简体) ), `role="alertdialog"`, (中文(简体) ), `aria-modal`, (中文(简体) ), `<dialog open>`),没有同意语言和单一的承认式按钮("我理解","得到它","OK",或一个 `aria-label="close"` 按钮)。 包含窗体字段的对话框不受影响,除非它们暴露出一个明显的关闭按钮,并且仅 `<button>` 元素被点击 所以解职永远无法导航。 它还包括了不具有对话作用的通知/推入选择上覆,例如AliExpress在标题上所制作的上覆:这些上覆只在副本涉及通知时才被点击,上覆坐落在一个位置小于取景口的容器中,它没有表单字段,也没有同意语言,它暴露出一种明确否定的控制("现在不是","没有许可证","尼赫特喷射",a `aria-label="close"` (b) 支付)。 肯定控制("Allow","Permitir")从未被点击过,链接中的控制被跳过,因此解职无法导航.

### 通知

通知默认被拒绝,所以网站跳过它们为索取而提供的覆盖. `Notification.permission` 财务报告和审定财务报表 `navigator.permissions.query({ name: 'notifications' })` 都读 `denied`,用于屏蔽通知的用户的Chrome对数值报告 `window.Notification` 继续暴露在克罗姆的体内.

权限属于页面浏览器的上下文,并应用在每次导航上,因此共享上下文的页面共享该值,且不使用 `goto` 保持克罗姆的默认值.

```js
// denied (default)
await goto(page, { url: 'https://example.com' })

// Chrome's out-of-the-box state, where `Notification.permission` reads `default`
await goto(page, { url: 'https://example.com', notifications: true })
```

### 脚本和样式注入

注入外部资源或内入代码 :

```js
await goto(page, {
  url: 'https://example.com',
  // External URLs
  scripts: ['https://cdn.example.com/library.js'],
  // ES modules
  modules: ['https://cdn.example.com/module.mjs'],
  // CSS (URLs, paths, or inline)
  styles: [
    'https://cdn.example.com/styles.css',
    'body { background: red; }'
  ]
})
```

### 请求拦截

中止特定资源类型以加快导航 :

```js
await goto(page, {
  url: 'https://example.com',
  abortTypes: ['image', 'stylesheet', 'font', 'media'],
  onPageRequest: (request, page) => {
    console.log('Request:', request.url())
  }
})
```

### 设备仿真

```js
// Use preset device
await goto(page, { url: 'https://example.com', device: 'iPhone 13' })

// Custom viewport
await goto(page, {
  url: 'https://example.com',
  viewport: { width: 1920, height: 1080 }
})

// Custom headers
await goto(page, {
  url: 'https://example.com',
  headers: {
    'user-agent': 'custom-agent',
    'cookie': 'session=abc123'
  }
})
```

### 返回值

这个 `goto` 函数返回 :

```js
const { response, device, error } = await goto(page, { url })

// response: Puppeteer Response object (or undefined if navigation failed)
// device: { userAgent, viewport } used for the request
// error: Error object if navigation failed
```

### 如何适合在单体

这是 **核心导航引擎** 用于整个无浏览器生态系统:

| 消费者 | 目的 |
| --- | --- |
| `browserless` (核心数) | 权力 `.goto()`, (中文(简体) ), `.html()`, (中文(简体) ), `.text()`, (中文(简体) ), `.pdf()`, (中文(简体) ), `.screenshot()` |
| `@browserless/screenshot` | 抓取截图前的导航 |
| `@browserless/pdf` | 生成 PDF 之前的导航 |
| `@browserless/function` | 沙盒函数执行的导航 |
| `@browserless/lighthouse` | 灯塔审计导航 |

### 依赖关系

| 软件包 | 目的 |
| --- | --- |
| `@browserless/devices` | 设备描述符查看并模拟 |
| `@ghostery/adblocker-puppeteer` | 阿德和跟踪器屏蔽 |
| `debug-logfmt` | 结构化调试日志 |
| `got` | 邮购脚本的 HTTP 客户端 |
| `is-url-http` | 检测值是否为注入的 URL |
| `p-reflect` 编号 : `p-timeout` | 承诺公用事业暂停 |
| `shallow-equal` | 查看端口比较优化 |
| `tough-cookie` | Cookie 字符串解析 |

## 许可证

**@ 浏览器无/去** © [微链接](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/goto 是什么？

导航到网页时带有内置的ad屏蔽,设备仿真,并优化加载,以加快自动化\.

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

在项目目录运行 npm install @browserless/goto，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：puppeteer（25）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

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

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

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

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

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

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

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

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

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

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

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

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