brightdata-sdk-js

Bright Data JavaScript SDK

通过统一的 Node.js/TypeScript SDK（@brightdata/sdk）访问网络数据。一个 客户端，提供多种服务：网页解锁（scrapeUrl）、平台抓取 （scrape.<platform>）、SERP 搜索（search.google/bing/yandex）、AI 发现 （discover）、数据集、浏览器自动化和 Scraper Studio。

需要 Node.js ≥ 20。 提供 ESM + CommonJS，并包含完整的 TypeScript 类型。 客户端导出为 bdclient（全小写，不是拼写错误）。

设置门槛（先完成）

npm install @brightdata/sdk     # or: pnpm add / yarn add

客户端会读取 BRIGHTDATA_API_TOKEN 环境变量，也可以传入 { apiKey }。 在 https://brightdata.com/cp/setting/users 获取令牌。

// ESM (package.json "type": "module", or .mjs)
import { bdclient } from '@brightdata/sdk';

// CommonJS (.cjs / "type": "commonjs")
const { bdclient } = require('@brightdata/sdk');

const client = new bdclient();             // reads BRIGHTDATA_API_TOKEN
// const client = new bdclient({ apiKey: '...' });
try {
  const html = await client.scrapeUrl('https://example.com');
} finally {
  await client.close();                    // always close (or `await using`)
}

await using client = new bdclient()（TS 5.2+ / Node ≥20）会在作用域结束时自动关闭。

服务选择（先决定，再查找方法）

在选择具体方法之前，先选定服务。大多数路由错误 都源于跳过这一步，直接根据关键词匹配。

Have a URL?
  ├── On a supported platform (Amazon, LinkedIn, Facebook, Instagram, YouTube,
  │   TikTok, Reddit, Pinterest, ChatGPT, Perplexity, DigiKey)?
  │     → Platform scraping: client.scrape.<platform>.<method>(urls, opts?)
  │
  ├── Generic page (no dedicated platform scraper)?
  │     → Web unlocker: client.scrapeUrl(url, { dataFormat: 'markdown' })
  │
  └── Need login / JS / click-scroll-fill / CAPTCHA / multi-step nav?
        → Browser API: client.browser.getConnectUrl() (connect via Playwright)

No URL?
  ├── Want entities matching natural-language criteria
  │   ("find AI startups in Berlin", "competitors of Acme")?
  │     → Discover: client.discover(query, { intent })
  │
  ├── Want web pages / search-result links ("search Google for X")?
  │     → SERP: client.search.google(query) [or .bing / .yandex]
  │
  ├── Want to search WITHIN a platform ("Amazon products by keyword",
  │   "LinkedIn jobs", "Instagram reels by profile")?
  │     → Platform discovery: client.scrape.<platform>.discover*(filters)
  │       or amazon.productSearch(...)  (NOTE: client.search is SERP-only here)
  │
  └── Want bulk/historical data at scale?
        → Datasets: client.datasets.<name>.query(filter) → .download(snapshotId)

边缘情况：

• URL 属于受支持的平台，但用户提到了登录/点击/滚动/JS → 使用 Browser API（交互需求优先于平台类型）。
• 受支持平台的抓取返回 403/被拦截 → 回退到 client.scrapeUrl()（网页解锁器）。
• “查找/研究 X 是谁”，并附带一个 URL（如“acme.com 的竞争对手”）→ 仍使用 Discover；URL 是上下文，而非抓取目标。

⚠️ 与 Python SDK 的主要区别

如果你熟悉 Python SDK（brightdata-sdk），请注意 JS 接口不同——不要 盲目照搬名称：

概念	Python	JavaScript
客户端	SyncBrightDataClient / BrightDataClient	bdclient（单一客户端，全部为异步）
网页解锁器	client.scrape_url(url=...)	client.scrapeUrl(url, opts)
平台搜索	client.search.amazon.products(...)	无 — 使用 scrape.amazon.productSearch / discover*
client.search	SERP 和平台搜索	仅 SERP（google/bing/yandex）
批处理	*_trigger 方法 + job.wait()	向单次调用传入 string[]，或使用 *Trigger + job.wait()
命名	snake_case	camelCase
数据集	client.datasets.amazon_products	client.datasets.amazonProducts

方法名称：使用前先确认

在断言某个平台方法存在或不存在之前，请查阅 references/scrapers.md——其中列出了每个平台已验证的方法。SDK 附带 TypeScript 类型，因此在有类型的项目中，也可以让编译器/编辑器 确认方法是否存在。

每个平台最多提供三种方法风格（见 references/scrapers.md）：

• collect<Thing>(input, opts?) — 直接返回各行数据（object[]）。
• <thing>(input, opts?) — 编排式调用（触发 → 轮询 → 下载）；返回 { data, status, rowCount }。默认使用此方式。
• discover<Thing>By<X>(filters, opts?) — 按关键词/类别/URL 筛选条件查找项目，而不是通过直接 URL 查找。

可能出现的幻觉（切勿使用这些写法——请在 references/scrapers.md 中确认）：

错误	正确
client.search.amazon.products(...)	client.scrape.amazon.productSearch(...)（JS 中没有平台搜索路由）
client.scrape.linkedin.people(...)	client.scrape.linkedin.profiles(urls)
client.scrape.chatgpt...	client.scrape.chatGPT...（camelCase，G+T 大写）
client.datasets.amazon_products	client.datasets.amazonProducts
BrightDataClient / new BdClient()	bdclient（全小写）

实用的独立方法

方法	功能
client.scrapeUrl(url | url[], opts?)	网页解锁器——任意 URL → html / markdown / json / 截图。传入数组可并行批量处理。
client.search.google(q | q[], opts?)	SERP 结果（也支持 .bing、.yandex）。传入数组可批量处理。
client.discover(query, { intent })	按 AI 排序的实体/页面发现。
client.discoverTrigger(query, opts?)	非阻塞式发现 → 返回带有 .wait() / .fetch() 的 Job。
client.datasets.list()	在运行时列出所有可用的数据集。
client.scraperStudio.run(collectorId, { input })	运行自定义的 Scraper Studio 收集器。
client.browser.getConnectUrl({ country })	用于 Playwright/Puppeteer/Selenium 的 CDP WebSocket URL。
client.listZones()	列出活跃的 Bright Data 区域。
client.saveResults(data, { filename, format })	将结果写入文件。
client.close()	关闭 HTTP 连接。完成后务必调用。

注意事项

• 务必调用 await client.close()（或使用 await using）。客户端持有 keep-alive 传输；若未释放，会导致进程挂起。
• client.search 仅用于 SERP（google/bing/yandex）。若要在某个平台内搜索，请使用该平台的 discover* / productSearch 抓取方法——没有 client.search.amazon。
• chatGPT 在 client.scrape 中使用驼峰命名——应调用 client.scrape.chatGPT.search(...)，而不是 .chatgpt。
• 批量处理：传入数组，不要循环调用。 scrapeUrl([...urls]) 和 search.google([...queries]) 会在内部并行运行。对于有大量输入的平台抓取器，优先使用传入数组的编排方法，或采用 *Trigger + job.wait() 模式（参见 references/advanced.md）。不要将阻塞调用包装在针对单项调用的 Promise.all 中——这会与速率限制器冲突。
• 编排方法会阻塞数分钟。 products/profiles/等方法会触发任务并轮询，直到任务就绪（通常需要 2–10 min）。不要设置过小的 pollTimeout；请通过 { pollInterval, pollTimeout } 调整。默认值经过校准。
• 数据集是历史/批量数据，不是实时数据。 需要当前数据时 → 使用平台抓取器或 scrapeUrl。query() 会返回 snapshotId；download() 会阻塞，直到快照就绪。
• 遇到 403 时使用网页解锁器回退。 如果平台抓取器受阻，请通过 client.scrapeUrl() 重试该 URL。
• 不要自行添加重试循环。 传输层已通过退避机制重试网络/超时错误；重复重试会浪费额度。请在构造函数中调整 timeout / rateLimit。
• 成本层级（从低到高）： 数据集 → SERP → 平台抓取器 → 网页解锁器 → discover → Scraper Studio → Browser API。优先选择满足请求的最低成本服务。

错误处理

所有错误都继承自 BRDError。导入特定类以进行分支处理：

import { bdclient, ValidationError, AuthenticationError, BRDError } from '@brightdata/sdk';

try {
  const data = await client.scrape.amazon.products(['https://www.amazon.com/dp/B0D77BX8Y4']);
} catch (err) {
  if (err instanceof AuthenticationError) { /* bad/expired token */ }
  else if (err instanceof ValidationError) { /* bad input */ }
  else if (err instanceof BRDError) { /* any SDK error */ }
  else throw err;
}

类：BRDError（基类）、ValidationError、AuthenticationError、ZoneError、 NetworkError、NetworkTimeoutError、TimeoutError、APIError、 DataNotReadyError、FSError。

示例

将通用页面抓取为 markdown

const md = await client.scrapeUrl('https://example.com/article', { dataFormat: 'markdown' });

获取 Amazon 商品（编排式——默认）

const res = await client.scrape.amazon.products(['https://www.amazon.com/dp/B0D77BX8Y4']);
console.log(res.status, res.rowCount, res.data);

批量获取 SERP

const results = await client.search.google(['best running shoes', 'best trail shoes'], { country: 'us' });

查找实体（Discover）

const startups = await client.discover('AI startups in Berlin', {
  intent: 'early-stage machine-learning companies',
  numResults: 10,
});

通过数据集获取批量/历史数据

const ds = client.datasets;
const snapshotId = await ds.instagramProfiles.query({ url: 'https://www.instagram.com/natgeo/' }, { records_limit: 50 });
// download() blocks until the snapshot is ready
const rows = await ds.instagramProfiles.download(snapshotId);

故障排除

• AuthenticationError / 401 — token 缺失或无效。检查 BRIGHTDATA_API_TOKEN 或 apiKey 选项。
• 403 / 受阻 — 网站阻止了抓取器。通过 client.scrapeUrl()（网页解锁器）重试该 URL。
• 超时 — 增大 timeout（构造函数参数，1000–300000 ms）或编排式 pollTimeout；不要调低。
• “Dataset not found” — 调用 client.datasets.list()；数据集名称采用驼峰命名（amazonProducts、linkedinProfiles）。
• 工作完成后进程仍挂起 — 忘记调用 await client.close()。
• 沙盒中的 SSL/代理错误 — 查看 references/advanced.md 了解区域/SSL 选项。
• 速率限制错误 — 在构造函数中设置 { rateLimit, ratePeriod }，或通过数组/触发器模式进行批量处理，而不是使用 Promise.all。

何时加载参考资料

• references/scrapers.md — 用户提及 Amazon、LinkedIn、Facebook、Instagram、YouTube、TikTok、Reddit、Pinterest、ChatGPT、Perplexity、DigiKey 时使用 — 按平台验证的方法表（collect / orchestrated / discover）以及 scrapeUrl 网页解锁器选项。
• references/search.md — SERP 引擎（search.google/bing/yandex）和 Discover API（discover / discoverTrigger），包含所有选项。
• references/datasets-overview.md — 数据集名称、query → getStatus → download 生命周期以及筛选条件。
• references/advanced.md — 构造函数选项和环境变量、批量/触发器编排、Browser API（Playwright/Puppeteer）、Scraper Studio、错误类以及区域/SSL。