Scraper Studio 函数参考 - Bright Data Docs

本参考文档记录了 Bright Data Scraper Studio IDE 中可用的每一个函数：控制浏览器会话的交互代码，以及将 HTML 转换为结构化记录的解析代码。每个函数都列出其参数、返回值和一个可运行的示例。

标有 ⭐ 的函数仅在 Browser worker 中有效，从 Code worker 调用时会抛出错误。完整列表见仅限浏览器的函数。

Scraper Studio 代码是如何组织的？

Bright Data Scraper Studio 抓取器使用两种代码类型：

代码类型	作用	语言和库
交互代码	导航目标站点：URL 请求、点击、滚动、等待和后台流量捕获	JavaScript + Bright Data 浏览器命令
解析代码	从交互代码返回的 HTML 中提取并结构化数据	JavaScript + Cheerio（`$`）

你可以通过 parse()（运行解析器）和 collect()（将一条记录追加到最终数据集）在两者之间传递数据。

交互函数

交互函数在抓取器的主 JavaScript 上下文中运行，并驱动浏览器或 HTTP 客户端。使用它们来导航、等待元素、与页面交互、捕获网络流量以及将数据移交给解析器。

全局对象

名称	类型	描述
`input`	object	当前阶段的输入，由触发器或前一个 `next_stage()`/`run_stage()`/`rerun_stage()` 调用设置。
`job`	object	有关当前作业的元数据（例如 `job.created`，作业开始时间戳）。
`location`	object	有关当前浏览器位置的信息。字段：`href`。
`parser`	object	由 `tag_response`、`tag_script` 及相关标记函数捕获的值，在 `wait_for_parser_value()` 之后可用。

navigate(input.url);
let {created} = job;
console.log('current url', location.href);

参数	类型	必填	默认值	描述
`url`	string 或 URL	是	,	目标 URL
`opt.wait_until`	string	否	`load`	`load`、`domcontentloaded`、`networkidle0` 或 `networkidle2`
`opt.timeout`	number	否	`30000`	导航超时（毫秒）
`opt.referer`	string	否	,	要发送的 `Referer` 请求头
`opt.allow_status`	number[]	否	`[]`	接受而不抛出错误的 HTTP 状态码
`opt.fingerprint`	object	否	,	覆盖浏览器指纹（`screen.width`、`screen.height`）

navigate(input.url);
navigate('https://example.com');
navigate('https://example.com', {wait_until: 'domcontentloaded'});
navigate('https://example.com', {referer: 'https://google.com'});
navigate('https://example.com', {timeout: 45000});
navigate('https://example.com', {allow_status: [404]});
navigate('https://example.com', {
  fingerprint: {screen: {width: 400, height: 400}},
});

`request`，发起直接 HTTP 请求

不使用浏览器发送 HTTP 请求。可在 Code worker 上使用，或在 Browser worker 上使用（当你想绕过浏览器时）。参数

参数	类型	必填	描述
`url` \| `options`	string 或 object	是	URL 字符串，或包含 `url`、`method`、`headers`、`body` 的对象

let res = request('https://www.example.com');
let res = request({
  url: 'https://www.example.com',
  method: 'POST',
  headers: {'Content-type': 'application/json'},
  body: {hello: 'world'},
});

`next_stage`，为下一阶段排队输入

在新的浏览器会话中使用给定输入运行抓取器的下一个阶段。参数

参数	类型	必填	描述
`input`	object	是	传递给下一阶段的输入对象

next_stage({url: 'https://example.com', page: 1});

`run_stage`，运行指定阶段

在新的浏览器会话中运行抓取器的某个命名阶段。参数

参数	类型	必填	描述
`stage`	number	是	阶段索引（从 1 开始）
`input`	object	是	传递给该阶段的输入对象

run_stage(2, {url: 'https://example.com', page: 1});

`rerun_stage`，用新输入重新运行当前阶段

使用新输入再次运行本阶段。用它来分散工作（例如，为分页中的每一页重新运行一次）。

rerun_stage({url: 'https://example.com/other-page'});

`load_sitemap`，从 XML 站点地图读取 URL

加载站点地图 XML 文件并返回 URL 列表。支持站点地图索引和 gzip 压缩的站点地图。参数

参数	类型	必填	描述
`options.url`	string	是	站点地图 URL

let {pages} = load_sitemap({url: 'https://example.com/sitemap.xml.gz'});
let {children} = load_sitemap({url: 'https://example.com/sitemap-index.xml'});

`resolve_url`，通过重定向追踪 URL

返回给定 URL 参数最终指向的 URL。参数

参数	类型	必填	描述
`url`	string 或 URL	是	要解析的 URL

let {href} = parse().anchor_elem_data;
collect({final_url: resolve_url(href)});

`redirect_history`，获取重定向链

返回自上次 navigate() 调用以来的 URL 重定向历史。

navigate('http://google.com');
let redirects = redirect_history();
// ['http://google.com', 'http://www.google.com', 'https://www.google.com/']

`response_headers`，读取最近一次响应的请求头

返回最近一次页面加载的响应头。

let headers = response_headers();
console.log('content-type', headers['content-type']);

`status_code`，读取最近一次响应的状态

返回最近一次页面加载的 HTTP 状态码。

collect({status_code: status_code()});

在页面上等待 ⭐

所有等待函数仅限 Browser worker。

⭐ `wait`，等待元素出现

参数

参数	类型	必填	默认值	描述
`selector`	string	是	,	要等待的 CSS 选择器
`opt.timeout`	number	否	`30000`	超时（毫秒）
`opt.hidden`	boolean	否	`false`	等待元素隐藏而非可见
`opt.inside`	string	否	,	要在其内部查找的 iframe 的选择器

wait('#welcome-splash');
wait('.search-results .product');
wait('[href^="/product"]');
wait('#welcome-splash', {timeout: 5000});
wait('#welcome-splash', {hidden: true});
wait('#welcome-splash', {inside: '#iframe_id'});

⭐ `wait_any`，等待多个条件中的任意一个

等待任意一个匹配条件成功。当第一个选择器解析成功时返回。

wait_any(['#title', '#notfound']);

⭐ `wait_visible`，等待元素可见

参数

参数	类型	必填	默认值	描述
`selector`	string	是	,	CSS 选择器
`opt.timeout`	number	否	`30000`	超时（毫秒）

wait_visible('#welcome-splash');
wait_visible('#welcome-splash', {timeout: 5000});

⭐ `wait_hidden`，等待元素消失

参数

参数	类型	必填	默认值	描述
`selector`	string	是	,	CSS 选择器
`opt.timeout`	number	否	`30000`	超时（毫秒）

wait_hidden('#welcome-splash');
wait_hidden('#welcome-splash', {timeout: 5000});

⭐ `wait_for_text`，等待文本内容

等待页面上的某个元素包含给定文本。参数

参数	类型	必填	描述
`selector`	string	是	CSS 选择器
`text`	string	是	要等待的文本

wait_for_text('.location', 'New York');

`wait_for_parser_value`，等待解析器字段被填充

在 tag_response() 或 tag_script() 之后使用，以等待捕获的数据可用。参数

参数	类型	必填	描述
`field`	string	是	要等待的解析器字段路径
`validate_fn`	function	否	可选回调，当值有效时返回 `true`
`opt.timeout`	number	否	超时（毫秒）

wait_for_parser_value('profile');
wait_for_parser_value('listings.0.price', v => parseInt(v) > 0, {timeout: 5000});

⭐ `wait_network_idle`，等待浏览器网络稳定

等待浏览器网络在给定时段内保持空闲。参数

参数	类型	必填	默认值	描述
`opt.timeout`	number	否	`500`	所需的空闲毫秒数
`opt.ignore`	array	否	`[]`	用于排除请求的模式（string 或 RegExp）

wait_network_idle();
wait_network_idle({
  timeout: 1e3,
  ignore: [/long_request/, 'https://example.com'],
});

⭐ `wait_page_idle`，等待 DOM 变更停止

等待 DOM 树在给定时段内不发生任何变化。参数

参数	类型	必填	描述
`opt.idle_timeout`	number	否	所需的稳定毫秒数
`opt.ignore`	array	否	要从变更监控中排除的选择器

wait_page_idle();
wait_page_idle({
  ignore: ['.live-clock', '.carousel'],
  idle_timeout: 1000,
});

元素交互 ⭐

所有交互函数都需要 Browser worker。

⭐ `click`，点击元素

点击元素，会先等待其出现。参数

参数	类型	必填	描述
`selector`	string 或 array	是	CSS 选择器或 Shadow DOM 选择器路径
`opt.coordinates`	`{x, y}`	否	点击距离给定页面坐标最近的匹配项

click('#show-more');
$('#show-more').click();

// Click the map pin closest to the center of a map
let box = bounding_box('#map');
let center = {x: (box.left + box.right) / 2, y: (box.top + box.bottom) / 2};
click('.map-pin', {coordinates: center});

⭐ `right_click`，右键点击元素

与 click 相同，但使用鼠标右键。

right_click('#item');

⭐ `hover`，悬停在元素上

将光标移动到元素上，会先等待其出现。

hover('#item');

⭐ `mouse_to`，将光标移动到某个坐标

参数

参数	类型	必填	描述
`x`	number	是	目标 X 位置
`y`	number	是	目标 Y 位置

mouse_to(0, 0);

⭐ `type`，向输入框输入文本

等待输入框出现，然后输入给定文本。参数

参数	类型	必填	描述
`selector`	string	是	CSS 选择器
`text`	string 或 array	是	要输入的文本，或由字符串和特殊键组成的数组
`opt.replace`	boolean	否	输入前清除现有文本

type('#location', 'New York');
type('#location', 'New York', {replace: true});
type('[id$=input-box]', 'search term');
type('#search', ['Some text', 'Enter']);
type('#search', ['Backspace']);

⭐ `press_key`，按下特殊键

在当前聚焦的输入框中输入 Enter 或 Backspace 等特殊键。

press_key('Enter');
press_key('Backspace');

⭐ `select`，从 select 元素中选取一个值

参数

参数	类型	必填	描述
`selector`	string	是	`<select>` 元素的 CSS 选择器
`value`	string	是	选项值或可见文本

select('#country', 'Canada');

⭐ `scroll_to`，将元素滚动到视图中

滚动页面，使目标元素可见。默认使用自然滚动；传入 immediate: true 可直接跳转。

scroll_to('.author-profile');
scroll_to('top');
scroll_to('bottom');
scroll_to('top', {immediate: true});

⭐ `scroll_to_all`，滚动经过每个匹配元素

scroll_to_all('.author-profiles');

⭐ `load_more`，触发懒加载内容

滚动到列表底部以触发无限滚动加载。参数

参数	类型	必填	描述
`selector`	string	是	容纳懒加载项的容器元素
`opt.children`	string	否	单个项目的选择器
`opt.trigger_selector`	string	否	显式”加载更多”按钮的选择器
`opt.timeout`	number	否	超时（毫秒）

load_more('.search-results');
load_more('.search-results', {
  children: '.result-item',
  trigger_selector: '.btn-load-more',
  timeout: 10000,
});

⭐ `close_popup`，在后台自动关闭弹窗

注册一个后台监视器，每当弹窗出现时将其关闭。推荐的模式见最佳实践。参数

参数	类型	必填	描述
`popup_selector`	string	是	弹窗容器的选择器
`close_selector`	string	是	关闭它的元素的选择器
`opt.click_inside`	string	否	父 iframe 选择器，如果关闭按钮位于 iframe 内

close_popup('.popup', '.popup_close');
close_popup('iframe.with-popup', '.popup_close', {click_inside: 'iframe.with-popup'});

⭐ `solve_captcha`，解决页面上的验证码

solve_captcha();
solve_captcha({type: 'simple', selector: '#image', input: '#input'});

⭐ `bounding_box`，获取元素的页面坐标

返回第一个匹配元素相对于页面的边界框。参数

参数	类型	必填	描述
`selector`	string	是	CSS 选择器

let box = bounding_box('.product-list');
// box == {top, right, bottom, left, x, y, width, height}

`el_exists`，检查元素是否在页面上

参数

参数	类型	必填	默认值	描述
`selector`	string	是	,	CSS 选择器
`timeout`	number	否	`0`	最多等待 N 毫秒以等元素出现

el_exists('#example');            // true
el_exists('.does_not_exist');     // false
el_exists('.does_not_exist', 5e3); // false after 5 seconds

`el_is_visible`，检查元素是否可见

参数

参数	类型	必填	默认值	描述
`selector`	string	是	,	CSS 选择器
`timeout`	number	否	`0`	最多等待 N 毫秒以等元素可见

el_is_visible('#example');
el_is_visible('.is_not_visible', 5e3);

⭐ `track_event_listeners`，开始跟踪浏览器事件监听器

必须在 disable_event_listeners() 之前调用。

track_event_listeners();

⭐ `disable_event_listeners`，禁用事件监听器

阻止页面上所有事件监听器运行。参数

参数	类型	必填	描述
`event_types`	string[]	否	要禁用的特定事件类型

disable_event_listeners();
disable_event_listeners(['hover', 'click']);

⭐ `freeze_page`，停止后续的页面变更

强制页面停止变化，使 HTML 快照准确反映抓取器所看到的内容。实验性功能。

freeze_page();

网络与响应标记 ⭐

标记会捕获后台网络流量并将其暴露给解析器。所有 tag_* 函数仅限 Browser worker。

⭐ `tag_response`，保存一个匹配的响应

保存来自某个匹配浏览器请求的响应数据。参数

参数	类型	必填	描述
`field`	string	是	要填充的解析器字段名称
`pattern`	RegExp 或 function	是	URL 模式或匹配函数
`opt.jsonp`	boolean	否	解析 JSONP 响应体（尽可能自动检测）
`opt.allow_error`	boolean	否	捕获非 2xx 状态码的响应

tag_response('resp', /url/, {jsonp: true});
tag_response('resp', /url/, {allow_error: true});

tag_response('resp', (req, res) => {
  if (req.url.includes('/api/')) {
    return {
      request_body: req.body,
      request_headers: req.headers,
      response_body: res.body,
      response_headers: res.headers,
    };
  }
});

tag_response('teams', /\/api\/teams/);
navigate('https://example.com/sports');
let teams = parse().teams;
for (let team of teams)
  collect(team);

⭐ `tag_all_responses`，保存每个匹配的响应

将每个匹配请求的响应数据保存为一个数组。

tag_all_responses('profiles', /\/api\/profile/);
navigate('https://example.com/sports');
let profiles = parse().profiles;
for (let profile of profiles)
  collect(profile);

⭐ `tag_script`，提取嵌入在 `<script>` 标签中的 JSON

参数

参数	类型	必填	描述
`field`	string	是	解析器字段名称
`selector`	string	是	script 标签选择器

tag_script('ssr_state', '#__SSR_DATA__');
navigate('https://example.com/');
collect(parse().ssr_state);

⭐ `tag_window_field`，标记浏览器 `window` 上的一个值

参数

参数	类型	必填	描述
`field`	string	是	解析器字段名称
`key`	string	是	要读取的 `window` 属性

tag_window_field('initData', '__INIT_DATA__');

⭐ `tag_image`，从 DOM 元素捕获图片 URL

tag_image('image', '#product-image');

⭐ `tag_video`，从 DOM 元素捕获视频 URL

参数

参数	类型	必填	描述
`field`	string	是	解析器字段名称
`selector`	string	是	元素选择器
`opt.download`	boolean	否	下载视频文件

tag_video('video', '#product-video', {download: true});

⭐ `tag_screenshot`，保存页面截图

参数

参数	类型	必填	描述
`field`	string	是	解析器字段名称
`opt.filename`	string	否	输出文件名
`opt.full_page`	boolean	否	默认为 `true`

tag_screenshot('html_screenshot', {filename: 'screen'});
tag_screenshot('view', {full_page: false});

⭐ `tag_download`，捕获浏览器下载的文件

参数

参数	类型	必填	描述
`url`	string 或 RegExp	是	匹配下载请求的模式

let SEC = 1000;
let download = tag_download(/example.com\/foo\/bar/);
click('button#download');
let file1 = download.next_file({timeout: 10 * SEC});
let file2 = download.next_file({timeout: 20 * SEC});
collect({file1, file2});

⭐ `tag_serp`，将页面解析为搜索引擎结果页

参数

参数	类型	必填	描述
`field`	string	是	解析器字段名称
`type`	string	是	解析器类型：`google`、`bing` 等

tag_serp('serp_bing_results', 'bing');
tag_serp('serp_google_results', 'google');

⭐ `capture_graphql`，捕获并重放 GraphQL 查询

捕获一个 GraphQL 请求，以便你可以用不同的变量重放它。参数

参数	类型	必填	描述
`options.payload`	object	是	与目标请求负载匹配的键值对
`options.url`	RegExp	否	GraphQL 端点的 URL 模式（默认为 `/graphql/`）

let q = capture_graphql({
  payload: {id: 'ProfileQuery'},
});
navigate('https://example.com');

let [first_query, first_response] = q.wait_captured();
collect(first_response.data.profile);

let second = q.replay({
  variables: {other_id: 2},
});
collect(second.data.profile);

数据采集

`parse`，运行解析器代码

运行解析器代码并返回结构化结果。

let page_data = parse();
collect({
  title: page_data.title,
  price: page_data.price,
});

`collect`，向数据集追加一条记录

向抓取器的输出添加一条记录。参数

参数	类型	必填	描述
`data_line`	object	是	要采集的字段
`validate_fn`	function	否	遇到无效数据时抛出错误的回调

collect({price: data.price});
collect(product, p => {
  if (!p.title)
    throw new Error('Product is missing a title');
});

`set_lines`，设置输出行，覆盖先前的调用

每次调用 set_lines() 都会覆盖前一次调用。当抓取器采集部分数据，并且你希望在后续步骤抛出错误时交付最后已知状态时，此函数很有用。参数

参数	类型	必填	描述
`lines`	object[]	是	记录数组
`validate_fn`	function	否	验证回调，每行运行一次

set_lines(products_so_far);
set_lines(products_so_far, p => {
  if (!p.price)
    throw new Error('Missing price');
});

`load_html`，将 HTML 字符串加载到 Cheerio

参数

参数	类型	必填	描述
`html`	string	是	要解析的 HTML

let $$ = load_html('<p id="p1">p1</p><p id="p2">p2</p>');
collect({data: $$('#p2').text()});

将一次抓取标记为失败

`bad_input`，将输入标记为无效

阻止任何重试并报告 error_code=bad_input。

bad_input();
bad_input('Missing search term');

`blocked`，将页面标记为已被阻止

报告站点拒绝访问。error_code=blocked。

blocked();
blocked('Login page was shown');

`dead_page`，将 URL 标记为失效链接

标记页面，以便在未来的采集中将其过滤掉。error_code=dead_page。

dead_page();
dead_page('Product was removed');

⭐ `detect_block`，检测页面上的阻止情况

参数

参数	类型	必填	描述
`resource.selector`	string	是	要检查的元素
`condition.exists`	boolean	否	如果元素存在则失败
`condition.has_text`	string 或 RegExp	否	如果元素包含匹配文本则失败

detect_block({selector: '.foo'}, {exists: true});
detect_block({selector: '.bar'}, {has_text: 'text'});
detect_block({selector: '.baz'}, {has_text: /regex_pattern/});

会话与路由

`country`，通过特定国家/地区路由

参数

参数	类型	必填	描述
`code`	string	是	两字符 ISO 国家/地区代码

country('us');

⭐ `proxy_location`，细粒度代理位置

除非你需要精确的地理控制，否则优先使用 country()。参数

参数	类型	必填	描述
`configuration.country`	string	否	两字符 ISO 国家/地区代码
`configuration.lat`	number	否	纬度，范围 `[-85, 85]`
`configuration.long`	number	否	经度，范围 `[-180, 180]`
`configuration.radius`	number	否	半径（千米）

proxy_location({country: 'us'});
proxy_location({lat: 37.7749, long: 122.4194});
proxy_location({lat: 37.7749, long: 122.4194, country: 'US', radius: 100});

`preserve_proxy_session`，在子阶段之间复用代理会话

preserve_proxy_session();

参数

参数	类型	必填	描述
`domain`	string	是	Cookie 域
`name`	string	是	Cookie 名称
`value`	string	是	Cookie 值

set_session_cookie('example.com', 'session_id', 'abc123');

`set_session_headers`，设置额外的 HTTP 请求头

参数

参数	类型	必填	描述
`headers`	object	是	请求头键值对

set_session_headers({'X-Custom-Header': 'value'});

浏览器配置 ⭐

仅限 Browser worker。

⭐ `browser_size`，获取当前浏览器窗口大小

以像素返回 {width, height}。

let size = browser_size();
console.log(size.width, size.height);

⭐ `emulate_device`，模拟移动设备

切换用户代理、屏幕分辨率和设备像素比，以匹配某个命名设备。参数

参数	类型	必填	描述
`device`	string	是	设备名称，例如 `iPhone X`、`Pixel 2`

emulate_device('iPhone X');
emulate_device('Pixel 2');

支持的设备名称完整列表

Blackberry PlayBook / landscape
BlackBerry Z30 / landscape
Galaxy Note 3 / landscape
Galaxy Note II / landscape
Galaxy S III / S5 / S8 / S9+（各含 landscape）
Galaxy Tab S4 / landscape
iPad / iPad Mini / iPad Pro / iPad Pro 11 / iPad (gen 6) / iPad (gen 7)（各含 landscape）
iPhone 4, 5, 6, 6 Plus, 7, 7 Plus, 8, 8 Plus, SE, X, XR, 11, 11 Pro, 11 Pro Max, 12 / 12 Mini / 12 Pro / 12 Pro Max, 13 / 13 Mini / 13 Pro / 13 Pro Max（各含 landscape）
JioPhone 2 / landscape
Kindle Fire HDX / landscape
LG Optimus L70 / landscape
Microsoft Lumia 550, 950（950 含 landscape）
Nexus 4, 5, 5X, 6, 6P, 7, 10（各含 landscape）
Nokia Lumia 520 / landscape，Nokia N9 / landscape
Pixel 2, 2 XL, 3, 4, 4a (5G), 5（各含 landscape）
Moto G4 / landscape

⭐ `font_exists`，检查浏览器字体支持

断言浏览器可以渲染给定的字体系列。

font_exists('Liberation Mono');

⭐ `html_capture_options`，配置 HTML 捕获

控制 HTML 快照的捕获方式。参数

参数	类型	必填	描述
`options.coordinate_attributes`	boolean	否	将元素坐标作为属性嵌入

html_capture_options({
  coordinate_attributes: true,
});

`embed_html_comment`，向页面 HTML 注入注释

在 HTML 快照中嵌入元数据。

embed_html_comment('trace-id: asdf123');

调试与可观测性

`console`，从交互代码记录日志

console.log(1, 'brightdata', [1, 2], {key: 'value'});
console.error('something went wrong');

⭐ `verify_requests`，监控失败的浏览器请求

在每个失败的浏览器请求上触发回调。参数

参数	类型	必填	描述
`callback`	function	是	对每个失败的请求以 `{url, error, type, response}` 调用

verify_requests(({url, error, type, response}) => {
  if (response.status != 404 && type == 'Font')
    throw new Error('Font failed to load');
});

值构造函数

Bright Data Scraper Studio 为结构化输出字段提供了带类型的构造函数。

`Image`、`Video`、`Pdf`、`Doc`、`Money`

构造函数	参数	用途
`Image(src)`	`src`：图片 URL 或 data URI	采集图片数据
`Video(src)`	`src`：视频 URL	采集视频数据
`Pdf(src)`	`src`：PDF URL	采集 PDF 文件
`Doc(src)`	`src`：文档文件 URL	采集文档文件
`Money(value, currency)`	`value`：数字，`currency`：ISO 代码	采集货币值

支持下载的文件类型

Scraper Studio 支持通过媒体和文档字段构造函数下载文件。使用方式：

new Image() 用于图片文件
new Video() 用于视频文件
new Pdf() 用于 PDF 文件
new Doc() 用于受支持的文档、文本、音频、视频和结构化文件类型

`new Doc()` 支持的内容类型

new Doc() 支持以下内容类型：

application/json
application/pdf
application/rtf
application/vnd.openxmlformats-officedocument.wordprocessingml.document
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
application/vnd.ms-excel
application/xml
application/vnd.oasis.opendocument.spreadsheet
audio/mp3
audio/mp4
audio/webm
text/csv
text/html
text/plain
text/vtt
text/xml
video/iso.segment
video/MP2T
video/mp2t
video/mp4
video/webm

示例：

let img = new Image('https://example.com/image.png');
let vid = new Video('https://example.com/video.mp4');
let pdf = new Pdf('https://example.com/document.pdf');
let doc = new Doc('https://example.com/file.csv');
let price = new Money(10, 'USD');

collect({
image: img, 
video: vid, 
pdf, 
document: doc, 
product_price: price
});

`URL`

标准 Node.js URL 类。

let u = new URL('https://example.com');

解析函数

解析代码在交互代码调用 parse() 之后运行。它接收捕获的 HTML 和任何已标记的数据，并向交互代码返回单条记录（或记录数组）。解析代码使用 Cheerio，一个与 jQuery 兼容的 HTML 解析器。

解析代码中可用的全局对象

名称	类型	描述
`$`	Cheerio 实例	已加载页面 HTML
`input`	object	当前阶段输入
`location`	object	当前浏览器位置；字段：`href`
`parser`	object	在交互期间标记的值（来自 `tag_response`、`tag_script` 及相关函数）

let url = input.url;
let current_url = location.href;
$('#example').text();

Cheerio 辅助函数

Bright Data Scraper Studio 在标准 API 之上添加了自定义 Cheerio 方法。

`$(selector).text_sane()`，规范化空白字符

返回 text()，其中所有连续的空白字符被折叠为单个空格并去除首尾空白。

let name = $('a').text_sane();                   // "foo bar baz"
let raw  = $('a').text();                        // "foo   bar\n\n\t baz"

`$(selector).filter_includes(text)`，按文本内容筛选元素

将选择集筛选为文本包含给定子串的元素。可与 Cheerio API 的其余部分链式调用。

$('.selector').filter_includes('text').click();

解析器值构造函数

Image、Video、PDF 和 Money 在解析代码中同样可用，且工作方式相同。

let img = new Image('https://example.com/image.png');
let price = new Money(10, 'USD');
let p = new Pdf('https://example.com/document.pdf')
collect({image: img, product_price: price});

验证已下载媒体的类型

使用 validate_type 检查已下载文件的内容是否与预期的媒体类型匹配。此选项由 new Pdf()、new Image() 和 new Video() 支持。启用 validate_type 后，Scraper Studio 会在获取文件后对其进行验证。如果文件内容与预期类型不匹配，该字段将返回错误，而不是有效的已下载文件。示例：

return {
  pdf: new Pdf('https://example.com/pdf', { validate_type: true }),
  image: new Image('https://example.com/image', { validate_type: true }),
  video: new Video('https://example.com/video', { validate_type: true }),
};

验证失败示例：

{
  "pdf": {
    "remote_url": "https://example.com/pdf",
    "error": "downloaded file type \"image\" does not match the expected \"pdf\" type",
    "validated_type": "image",
    "error_code": "wrong_file_type"
  }
}

有关完整的 Cheerio API 文档，请参阅 Cheerio 网站。

Shadow DOM 支持

接受选择器的交互命令也接受选择器数组，让你能够深入 Shadow DOM 树。可将其与 click、wait、type 及其他交互函数一起使用。当你传入数组时：

其中一个选择器必须指向 shadow host 元素
它之后的每个选择器都在该 shadow root 内解析

click(['body', 'my-shadow-host', 'button.submit']);

在该示例中，my-shadow-host 是附加了 shadow root 的元素，而 button.submit 在该 shadow root 内解析。

仅限浏览器的函数

以下函数需要 Browser worker，从 Code worker 调用时会抛出 not_supported_in_code_worker。使用此列表来决定你的抓取器需要哪种 worker。

类别	函数
等待	`wait`、`wait_any`、`wait_for_text`、`wait_visible`、`wait_hidden`、`wait_network_idle`、`wait_page_idle`
交互	`click`、`right_click`、`hover`、`mouse_to`、`type`、`press_key`、`select`、`scroll_to`、`scroll_to_all`、`load_more`、`close_popup`、`solve_captcha`
标记	`tag_response`、`tag_all_responses`、`tag_script`、`tag_window_field`、`tag_image`、`tag_video`、`tag_screenshot`、`tag_download`、`tag_serp`、`capture_graphql`
浏览器配置	`browser_size`、`emulate_device`、`font_exists`、`html_capture_options`、`freeze_page`、`track_event_listeners`、`disable_event_listeners`

请参阅 Worker 类型以在 Browser worker 和 Code worker 之间做出选择。

最佳实践

编写快速、可靠抓取器的推荐模式

Worker 类型

何时使用 Browser worker 与 Code worker

网页抓取基础

核心概念：交互、解析、阶段和规模

开发抓取器

在 IDE 中构建抓取器的逐步演示

​Scraper Studio 代码是如何组织的？

​交互函数

​全局对象

​导航

​navigate，在浏览器中加载 URL

​request，发起直接 HTTP 请求

​next_stage，为下一阶段排队输入

​run_stage，运行指定阶段

​rerun_stage，用新输入重新运行当前阶段

​load_sitemap，从 XML 站点地图读取 URL

​resolve_url，通过重定向追踪 URL

​redirect_history，获取重定向链

​response_headers，读取最近一次响应的请求头

​status_code，读取最近一次响应的状态

​在页面上等待 ⭐

​⭐ wait，等待元素出现

​⭐ wait_any，等待多个条件中的任意一个

​⭐ wait_visible，等待元素可见

​⭐ wait_hidden，等待元素消失

​⭐ wait_for_text，等待文本内容

​wait_for_parser_value，等待解析器字段被填充

​⭐ wait_network_idle，等待浏览器网络稳定

​⭐ wait_page_idle，等待 DOM 变更停止

​元素交互 ⭐

​⭐ click，点击元素

​⭐ right_click，右键点击元素

​⭐ hover，悬停在元素上

​⭐ mouse_to，将光标移动到某个坐标

​⭐ type，向输入框输入文本

​⭐ press_key，按下特殊键

​⭐ select，从 select 元素中选取一个值

​⭐ scroll_to，将元素滚动到视图中

​⭐ scroll_to_all，滚动经过每个匹配元素

​⭐ load_more，触发懒加载内容

​⭐ close_popup，在后台自动关闭弹窗

​⭐ solve_captcha，解决页面上的验证码

​⭐ bounding_box，获取元素的页面坐标

​el_exists，检查元素是否在页面上

​el_is_visible，检查元素是否可见

​⭐ track_event_listeners，开始跟踪浏览器事件监听器

​⭐ disable_event_listeners，禁用事件监听器

​⭐ freeze_page，停止后续的页面变更

​网络与响应标记 ⭐

​⭐ tag_response，保存一个匹配的响应

​⭐ tag_all_responses，保存每个匹配的响应

​⭐ tag_script，提取嵌入在 <script> 标签中的 JSON

​⭐ tag_window_field，标记浏览器 window 上的一个值

​⭐ tag_image，从 DOM 元素捕获图片 URL

​⭐ tag_video，从 DOM 元素捕获视频 URL

​⭐ tag_screenshot，保存页面截图

​⭐ tag_download，捕获浏览器下载的文件

​⭐ tag_serp，将页面解析为搜索引擎结果页

​⭐ capture_graphql，捕获并重放 GraphQL 查询

​数据采集

​parse，运行解析器代码

​collect，向数据集追加一条记录

​set_lines，设置输出行，覆盖先前的调用

​load_html，将 HTML 字符串加载到 Cheerio

​将一次抓取标记为失败

​bad_input，将输入标记为无效

​blocked，将页面标记为已被阻止

​dead_page，将 URL 标记为失效链接

​⭐ detect_block，检测页面上的阻止情况

​会话与路由

​country，通过特定国家/地区路由

​⭐ proxy_location，细粒度代理位置

​preserve_proxy_session，在子阶段之间复用代理会话

​set_session_cookie，为当前会话设置 cookie

​set_session_headers，设置额外的 HTTP 请求头

​浏览器配置 ⭐

​⭐ browser_size，获取当前浏览器窗口大小

​⭐ emulate_device，模拟移动设备

​⭐ font_exists，检查浏览器字体支持

​⭐ html_capture_options，配置 HTML 捕获

​embed_html_comment，向页面 HTML 注入注释

​调试与可观测性

​console，从交互代码记录日志

​⭐ verify_requests，监控失败的浏览器请求

​值构造函数

​Image、Video、Pdf、Doc、Money

Scraper Studio 代码是如何组织的？

交互函数

全局对象

导航

`navigate`，在浏览器中加载 URL

`request`，发起直接 HTTP 请求

`next_stage`，为下一阶段排队输入

`run_stage`，运行指定阶段

`rerun_stage`，用新输入重新运行当前阶段

`load_sitemap`，从 XML 站点地图读取 URL

`resolve_url`，通过重定向追踪 URL

`redirect_history`，获取重定向链

`response_headers`，读取最近一次响应的请求头

`status_code`，读取最近一次响应的状态

在页面上等待 ⭐

⭐ `wait`，等待元素出现

⭐ `wait_any`，等待多个条件中的任意一个

⭐ `wait_visible`，等待元素可见

⭐ `wait_hidden`，等待元素消失

⭐ `wait_for_text`，等待文本内容

`wait_for_parser_value`，等待解析器字段被填充

⭐ `wait_network_idle`，等待浏览器网络稳定

⭐ `wait_page_idle`，等待 DOM 变更停止

元素交互 ⭐

⭐ `click`，点击元素

⭐ `right_click`，右键点击元素

⭐ `hover`，悬停在元素上

⭐ `mouse_to`，将光标移动到某个坐标

⭐ `type`，向输入框输入文本

⭐ `press_key`，按下特殊键

⭐ `select`，从 select 元素中选取一个值

⭐ `scroll_to`，将元素滚动到视图中

⭐ `scroll_to_all`，滚动经过每个匹配元素

⭐ `load_more`，触发懒加载内容

⭐ `close_popup`，在后台自动关闭弹窗

⭐ `solve_captcha`，解决页面上的验证码

⭐ `bounding_box`，获取元素的页面坐标

`el_exists`，检查元素是否在页面上

`el_is_visible`，检查元素是否可见

⭐ `track_event_listeners`，开始跟踪浏览器事件监听器

⭐ `disable_event_listeners`，禁用事件监听器

⭐ `freeze_page`，停止后续的页面变更

网络与响应标记 ⭐

⭐ `tag_response`，保存一个匹配的响应

⭐ `tag_all_responses`，保存每个匹配的响应

⭐ `tag_script`，提取嵌入在 `<script>` 标签中的 JSON

⭐ `tag_window_field`，标记浏览器 `window` 上的一个值

⭐ `tag_image`，从 DOM 元素捕获图片 URL

⭐ `tag_video`，从 DOM 元素捕获视频 URL

⭐ `tag_screenshot`，保存页面截图

⭐ `tag_download`，捕获浏览器下载的文件

⭐ `tag_serp`，将页面解析为搜索引擎结果页

⭐ `capture_graphql`，捕获并重放 GraphQL 查询

数据采集

`parse`，运行解析器代码

`collect`，向数据集追加一条记录

`set_lines`，设置输出行，覆盖先前的调用

`load_html`，将 HTML 字符串加载到 Cheerio

将一次抓取标记为失败

`bad_input`，将输入标记为无效

`blocked`，将页面标记为已被阻止

`dead_page`，将 URL 标记为失效链接

⭐ `detect_block`，检测页面上的阻止情况

会话与路由

`country`，通过特定国家/地区路由

⭐ `proxy_location`，细粒度代理位置

`preserve_proxy_session`，在子阶段之间复用代理会话

`set_session_cookie`，为当前会话设置 cookie

`set_session_headers`，设置额外的 HTTP 请求头

浏览器配置 ⭐

⭐ `browser_size`，获取当前浏览器窗口大小

⭐ `emulate_device`，模拟移动设备

⭐ `font_exists`，检查浏览器字体支持

⭐ `html_capture_options`，配置 HTML 捕获

`embed_html_comment`，向页面 HTML 注入注释

调试与可观测性

`console`，从交互代码记录日志

⭐ `verify_requests`，监控失败的浏览器请求

值构造函数

`Image`、`Video`、`Pdf`、`Doc`、`Money`