# @brightdata/sdk 中文文档

规范地址：https://npmcn.com/package/%40brightdata/sdk/

版本：1\.2\.0
npm 元数据更新时间：2026-08-02T12:41:23.102Z
中文译文更新时间：2026-11-08T15:17:48.866Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40brightdata/sdk
原文对照：https://npmcn.com/package/%40brightdata/sdk/?lang=original
项目主页：https://github.com/brightdata/sdk-js#readme
源码仓库：https://github.com/brightdata/sdk-js

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

- 包体积（解压后）：754 kB，583 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：3 个
- 首次发布：2025-09-26T14:46:10.723Z
- 最新版本发布：2026-08-02T12:41:22.671Z
- 近 30 天下载量：73473（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 3 个）

## 中文简介

JavaScript SDK 用于亮相数据网络搜索和 SERP API

## 安装

```sh
npm install @brightdata/sdk
```

也可以使用：`pnpm add @brightdata/sdk`、`yarn add @brightdata/sdk`、`bun add @brightdata/sdk`

## README

![sdk-banner(1)](https://github.com/user-attachments/assets/c4a7857e-10dd-420b-947a-ed2ea5825cb8)

### 亮相 Data JavaScript SDK 为刮取,网络搜索,数据集等提供简单可扩展的方法.

## 安装 [![@latest](https://img.shields.io/npm/v/@brightdata/sdk.svg)](https://www.npmjs.com/package/@brightdata/sdk)

```bash
npm install @brightdata/sdk
```

## 快开始

### 1\. 联合国. [注册](https://brightdata.com/cp) 获取您的 API 令牌

### 2\. 初始化客户

```javascript
import { bdclient } from '@brightdata/sdk';

const client = new bdclient({
    apiKey: '[your_api_token]', // or set BRIGHTDATA_API_TOKEN env variable
});
```

### 3\. 发出你的第一个请求

```javascript
// Scrape a webpage
const html = await client.scrapeUrl('https://example.com');
console.log(html);

// Search the web
const results = await client.search.google('pizza restaurants', { country: 'us' });
console.log(results);
```

不要忘记关闭 当完成:

```javascript
await client.close();
```

## 特征

-   **网络搜索** ——使用反机器人检测绕行和代理支持来搜索任何网站
-   **搜索引擎结果** ——Google, Bing, 有批量支持的Yandex搜索
-   **平台缓冲器** - 从LinkedIn、Amazon、Instagram、TikTok、YouTube、Reddit等机构收集结构化数据
-   **爬行 API** —— 抓取任意 URL并获得每页捆绑的每个输出格式( 标记下, HTML, 文本)
-   **发现 API** ——AI驱动的网络搜索,并基于意图的关联性排名
-   **史克威尔工作室** – Bright Data's Scraper Studio所建自定义刮取器的触发并获取结果
-   **浏览器 API** – CDP WebSocket URL 用于连接 Playwright, Puppeteer, 或 Selenium 到 Bright Data 的云浏览器
-   **数据集** ——通过数十个平台访问126个预建数据集,提供查询/下载支持
-   **并行处理** ——同时处理多个URL或查询
-   **强力错误处理** —— 有重试逻辑的打出错误类
-   **区管理** 自动区创建和管理
-   **多个输出格式** HTML、JSON、Markdown和截图
-   **双重构建** ——支持无害环境管理和共同JS
-   **类型脚本** ——满打的API有超载签名
-   **子路径导出** - 树木可移动进口 `@brightdata/sdk/scrapers`, (中文(简体) ), `@brightdata/sdk/search`, (中文(简体) ), `@brightdata/sdk/datasets`

## 使用量

### 拼接网站

```javascript
// Single URL — returns HTML string by default
const html = await client.scrapeUrl('https://example.com');

// Multiple URLs (parallel processing)
const results = await client.scrapeUrl([
    'https://example1.com',
    'https://example2.com',
]);

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

// Get structured JSON
const data = await client.scrapeUrl('https://example.com', {
    format: 'json',
});

// Take a screenshot
const screenshot = await client.scrapeUrl('https://example.com', {
    dataFormat: 'screenshot',
});

// Full options
const result = await client.scrapeUrl('https://example.com', {
    format: 'raw',            // 'raw' (default) or 'json'
    dataFormat: 'html',       // 'html' (default), 'markdown' (alias: 'md'), 'screenshot'
    country: 'gb',            // two-letter country code
    method: 'GET',            // HTTP method
});
```

### 搜索引擎

```javascript
// Google search
const results = await client.search.google('pizza restaurants');

// Bing search
const results = await client.search.bing('pizza restaurants');

// Yandex search
const results = await client.search.yandex('pizza restaurants');

// Batch search (parallel)
const results = await client.search.google(['pizza', 'sushi', 'tacos']);

// With options
const results = await client.search.google('pizza', {
    country: 'gb',
    format: 'json',
});
```

> **说明:** 若为 `country` 未指定,请求通过任意 代理位置,所以结果可能是地理定位到一个出乎意料的国家. 总是通过 `country` 当你需要一致的,局部的结果.

### 平台拆卸机

从流行平台收集结构化数据. 每个平台都支持同步收藏( E)`collect*`)和aync策划的刮去(触发,民意调查,下载).

```javascript
// LinkedIn profiles
const data = await client.scrape.linkedin.collectProfiles(
    ['https://www.linkedin.com/in/satyanadella/'],
    { format: 'json' },
);

// Amazon products
const data = await client.scrape.amazon.collectProducts(
    ['https://www.amazon.com/dp/B0D77BX8Y4'],
    { format: 'json' },
);

// Instagram profiles
const data = await client.scrape.instagram.collectProfiles(
    ['https://www.instagram.com/natgeo/'],
    { format: 'json' },
);

// TikTok profiles
const data = await client.scrape.tiktok.collectProfiles(
    ['https://www.tiktok.com/@tiktok'],
    { format: 'json' },
);

// YouTube videos
const data = await client.scrape.youtube.collectVideos(
    ['https://www.youtube.com/watch?v=dQw4w9WgXcQ'],
    { format: 'json' },
);

// Reddit posts
const data = await client.scrape.reddit.collectPosts(
    ['https://www.reddit.com/r/technology/top/'],
    { format: 'json' },
);
```

**乐器刮刮** (同步触发 民调 下载):

```javascript
const result = await client.scrape.linkedin.profiles(
    ['https://www.linkedin.com/in/satyanadella/'],
    { pollInterval: 5000, pollTimeout: 180_000 },
);
console.log(result.data);    // structured data
console.log(result.status);  // 'ready'
console.log(result.rowCount);
```

**可用的平台 :** `linkedin`, (中文(简体) ), `amazon`, (中文(简体) ), `instagram`, (中文(简体) ), `tiktok`, (中文(简体) ), `youtube`, (中文(简体) ), `reddit`, (中文(简体) ), `facebook`, (中文(简体) ), `pinterest`, (中文(简体) ), `chatGPT`, (中文(简体) ), `digikey`, (中文(简体) ), `perplexity`

### 爬行 API

抓取一个或多个 URL 并获得每页捆绑的每个输出格式(markdown, HTML, text).

```javascript
// Sync — single round-trip
const result = await client.crawler.crawl('https://example.com');
console.log(result.data[0].markdown);

// Batch
const result = await client.crawler.crawl([
    'https://example.com',
    'https://example.com/about',
]);
console.log(`${result.pageCount} pages`);

// Async — trigger, poll, download
const job = await client.crawler.trigger('https://example.com');
const status = await client.crawler.status(job.snapshotId);
const result = await client.crawler.download(job.snapshotId);
```

### 发现 API

AI驱动的网络搜索,根据意图进行关联性排名.

`discover()` 决定: `DiscoverResult` 包装( 不是赤色阵列) 。 项目 开始 `result.data` (或其别名) `result.results`结果确是永恒的. 失败时 `result.success` 实值 `false`, (中文(简体) ), `result.error` 带着理由,和 `result.data` 编号 : `result.results` 保留一个空阵列——所以不丢.

```javascript
// Basic search
const result = await client.discover('artificial intelligence trends 2026');

if (!result.success) {
    console.error('discover failed:', result.error);
} else {
    console.log(result.results); // [{ link, title, description, relevance_score }, ...]
    for (const item of result) {
        console.log(`[${item.relevance_score}] ${item.title}`);
    }
}

// With intent for semantic ranking
const result = await client.discover('Tesla battery technology', {
    intent: 'recent breakthroughs in EV battery chemistry',
});

// With filtering and localization
const result = await client.discover('sustainable fashion brands', {
    intent: 'eco-friendly clothing companies',
    filterKeywords: ['sustainability', 'eco-friendly', 'organic'],
    country: 'us',
    numResults: 10,
});

// Include full page content
const result = await client.discover('python asyncio tutorial', {
    includeContent: true,
    numResults: 3,
});

// Manual trigger/poll/fetch
const job = await client.discoverTrigger('market research SaaS', {
    intent: 'competitor pricing strategies',
});
await job.wait({ timeout: 60_000 });
const data = await job.fetch();
```

### 史克威尔工作室

触发并获取您自定义的剪贴机所建 [史克威尔工作室](https://brightdata.com/cp/data_collector)。 。 。 .

```javascript
// Orchestrated — trigger + poll + return results
const results = await client.scraperStudio.run('c_your_collector_id', {
    input: { url: 'https://example.com/product/1' },
});
// results: RunResult[] — one per input with { input, data, error, responseId, elapsedMs }

// Multiple inputs (processed sequentially)
const results = await client.scraperStudio.run('c_your_collector_id', {
    input: [
        { url: 'https://example.com/product/1' },
        { url: 'https://example.com/product/2' },
    ],
});

// Manual control — trigger, then poll yourself
const job = await client.scraperStudio.trigger('c_your_collector_id', {
    url: 'https://example.com/product/1',
});
const data = await job.waitAndFetch();

// Check job status (by job ID from the dashboard)
const status = await client.scraperStudio.status('j_abc123');
console.log(status.status); // 'queued' | 'running' | 'done' | 'failed'
```

### 浏览器 API

构建 CDP WebSocket URL,用于连接 Playwright, Puppeteer, 或 Selenium 到Bright Data 的云浏览器. 全权证书来自 `browserUsername`编号 :`browserPassword` 选项或 `BRIGHTDATA_BROWSERAPI_USERNAME`编号 :`BRIGHTDATA_BROWSERAPI_PASSWORD` (原始内容存档于2018-10-21). env vars.

```javascript
// Get a connection URL
const url = client.browser.getConnectUrl();

// Geo-target the browser with a 2-letter country code
const usUrl = client.browser.getConnectUrl({ country: 'us' });

// Connect with Playwright
import { chromium } from 'playwright';
const browser = await chromium.connectOverCDP(url);
const page = await browser.newPage();
await page.goto('https://example.com');
const html = await page.content();
await browser.close();
```

### 数据集

访问126个预建数据集,用于查询和下载结构化数据快照.

```javascript
const ds = client.datasets;

// List all datasets available on your account
const list = await ds.list();

// Get field metadata for a dataset
const meta = await ds.instagramProfiles.getMetadata();
console.log(meta.fields); // [{ name, type, description }, ...]

// Query a dataset (triggers a snapshot)
const snapshotId = await ds.instagramProfiles.query(
    { url: 'https://www.instagram.com/natgeo/' },
    { records_limit: 10 },
);

// Check snapshot status
const status = await ds.instagramProfiles.getStatus(snapshotId);
console.log(status.status); // 'running' | 'ready' | ...

// Download when ready
const rows = await ds.instagramProfiles.download(snapshotId);
```

**可用的数据集 :**

| 平台 | 数据集 |
| --- | --- |
| 链接 | `linkedinProfiles`, (中文(简体) ), `linkedinCompanies` |
| 亚马逊 | `amazonProducts`, (中文(简体) ), `amazonReviews`, (中文(简体) ), `amazonSellers`, (中文(简体) ), `amazonBestSellers`, (中文(简体) ), `amazonProductsSearch`, (中文(简体) ), `amazonProductsGlobal`, (中文(简体) ), `amazonWalmart` |
| 内存 | `instagramProfiles`, (中文(简体) ), `instagramPosts`, (中文(简体) ), `instagramComments`, (中文(简体) ), `instagramReels` |
| 叮当 | `tiktokProfiles`, (中文(简体) ), `tiktokPosts`, (中文(简体) ), `tiktokComments`, (中文(简体) ), `tiktokShop` |
| X / 图文 | `xTwitterPosts`, (中文(简体) ), `xTwitterProfiles` |

### 保存结果

```javascript
const data = await client.scrapeUrl('https://example.com');
const filePath = await client.saveResults(data, {
    filename: 'results.json',
    format: 'json',
});
console.log(`Saved to: ${filePath}`);
```

## 配置

### 运行时间支持

Node.js (QQ 20) 是支持和测试的运行时间. SDK也在Bun下方运行,没有崩溃,但有一个真正的警告:Bun被捆绑了 `undici` 只能提供裸骨 `Agent` (无) `compose()`,没有 `close()`,没有自定义 `dispatch`),和"邦"(Bun's) `request()`编号 :`stream()` 忽略 `dispatcher` 选项全部,通过 Bun 自己的本地 HTTP 客户端进行路由。 在实践中,这意味着请求在Bun下仍然成功,但运输的调子——连接集成、留守、自定义超时、自动重试429/500/502/503/504和DNS缓存——在这方面没有任何效果; Bun本身的默认适用。 SDK自动检测缺失的能力(从未崩溃构造或 `close()`而不是失败.

### API 托肯语Name

获取您的 API 令牌 [亮相数据控制面板](https://brightdata.com/cp/setting/users?=)。 。 。 .

**已经登录到CLI了? SDK没有配置.** 如果你已经跑 `brightdata login` 与 [亮数据 CLI](https://www.npmjs.com/package/@brightdata/cli),SDK自动取出那些存储的证书. 符号按此顺序解决:

1.  `apiKey` 转至 `new bdclient({ apiKey })`
2.  `BRIGHTDATA_API_TOKEN` (或 `BRIGHTDATA_API_KEY`() 环境变量
3.  由CLI存储的证书(`brightdata login`(中文(简体) )

如果没有找到,客户端会投放带有登录或设置符号的指示.

### 环境变量

```env
BRIGHTDATA_API_TOKEN=your_api_token                  # BRIGHTDATA_API_KEY also accepted
BRIGHTDATA_WEB_UNLOCKER_ZONE=your_web_unlocker_zone  # Optional
BRIGHTDATA_SERP_ZONE=your_serp_zone                  # Optional
BRIGHTDATA_BROWSERAPI_USERNAME=your_browser_username # Optional, for Browser API
BRIGHTDATA_BROWSERAPI_PASSWORD=your_browser_password # Optional, for Browser API
BRIGHTDATA_VERBOSE=1                                  # Optional, enable verbose logging
```

> **提示 :** 从 a 装入时 `.env` 文件为 `node --env-file=.env`, (中文(简体) ), 请注意,您 shell 中已经设定的变量优先于文件.

### 客户选项

```javascript
const client = new bdclient({
    apiKey: 'string',           // API token (or use BRIGHTDATA_API_TOKEN env var)
    timeout: 120000,            // Request timeout in ms (1000–300000)
    autoCreateZones: true,      // Auto-create zones if they don't exist
    webUnlockerZone: 'string',  // Custom web unlocker zone name
    serpZone: 'string',         // Custom SERP zone name
    logLevel: 'INFO',           // 'DEBUG' | 'INFO' | 'WARNING' | 'ERROR' | 'CRITICAL'
    structuredLogging: true,    // Use structured JSON logging
    verbose: false,             // Enable verbose logging
    rateLimit: 0,               // Max requests per period (0 = unlimited)
    ratePeriod: 1000,           // Rate limit period in ms
});
```

### 资源清理

客户端维持了HTTP连接. 完成时总是关闭 :

```javascript
await client.close();

// Or use Symbol.asyncDispose (TypeScript 5.2+)
await using client = new bdclient();
```

### 常数

| 常数 | 默认 | 说明 |
| --- | --- | --- |
| `DEFAULT_CONCURRENCY` | `10` | 最大并行任务 |
| `DEFAULT_TIMEOUT` | `120000` | 请求超时( 毫秒) |
| `MAX_RETRIES` | `3` | 尝试失败 |
| `RETRY_BACKOFF_FACTOR` | `1.5` | 指标倒置乘数 |

### 区管理

```javascript
const zones = await client.listZones();
console.log(`Found ${zones.length} zones`);
```

## 子路径导出

仅用于摇树或导入所需:

```javascript
import { ScrapeRouter, LinkedinAPI } from '@brightdata/sdk/scrapers';
import { SearchRouter } from '@brightdata/sdk/search';
import { DatasetsClient, BaseDataset } from '@brightdata/sdk/datasets';
```

## 处理错误

SDK 导出扩展的打出错误类别 `BRDError`数字 :

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

try {
    const result = await client.scrapeUrl('https://example.com');
} catch (error) {
    if (error instanceof ValidationError) {
        console.error('Invalid input:', error.message);
    } else if (error instanceof AuthenticationError) {
        console.error('Auth failed:', error.message);
    } else if (error instanceof BRDError) {
        console.error('SDK error:', error.message);
    }
}
```

**错误类型 :** `ValidationError`, (中文(简体) ), `AuthenticationError`, (中文(简体) ), `ZoneError`, (中文(简体) ), `NetworkError`, (中文(简体) ), `NetworkTimeoutError`, (中文(简体) ), `TimeoutError`, (中文(简体) ), `APIError`, (中文(简体) ), `DataNotReadyError`, (中文(简体) ), `FSError`

## 解决问题

### 视窗和公司网络

| 问题 | 修补 |
| --- | --- |
| `npm.ps1 cannot be loaded because running scripts is disabled` (PowerShell) (英语) | 使用 **(单位:千美元)** 代替 PowerShell , 或者运行 `npm.cmd <command>`,或运行 `Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned`如果被Group Policy所压倒,请联系您的IT团队. |
| `SELF_SIGNED_CERT_IN_CHAIN` 期间 `npm install` | 您的网络使用SSL检查。 公司根证书的npm: `npm config set cafile "C:\path\to\corporate-root.cer"` |
| 运行时的证书出错 | 设置嵌入变量 `NODE_EXTRA_CA_CERTS=C:\path\to\corporate-root.cer` 所以Node信任你的公司证书. |

### 认证错误: 无效的 API 密钥

如果您得到此错误, 请检查以下顺序 :

1.  **验证标志本身** 工作,在SDK之外:
    
    ```bash
    curl -H "Authorization: Bearer YOUR_TOKEN" https://api.brightdata.com/zone/get_active_zones
    ```
    
    如果失败, 将生成一个新的 API 密钥 **管理员** 权限 [控制面板](https://brightdata.com/cp/setting/users)。注意SDK的需要 账户级 API 令牌 – 不是区密码 .
2.  **检查外壳覆盖 .** 您 shell 中设置的环境变量 优先于 `.env` 装入的文件 `node --env-file=.env`运行 `set BRIGHTDATA` (窗户)或 `env | grep BRIGHTDATA` (macOS/Linux)和清晰 任何剩余值.
3.  **检查你的 `.env` 文件 :** 没有引用, 周围没有空格 `=`没有跟踪 白空格, 和符号完全复制( 包括破折号) 。 偏好 LF 线 结局.
4.  **打印实际装入的 :**
    
    ```js
    console.log(JSON.stringify(process.env.BRIGHTDATA_API_TOKEN));
    ```
    
    隐藏字符如 `\r` 将在输出中可见.

## 支助

关于任何问题,请联系 [亮数据支持](https://brightdata.com/contact),或者在此寄存器中打开一个问题.

## 许可证

本项目根据以下规定获得许可证: [MIT 许可证](https://opensource.org/licenses/MIT)。 。 。 .

## 常见问题

### @brightdata/sdk 是什么？

JavaScript SDK 用于亮相数据网络搜索和 SERP API

### 如何安装 @brightdata/sdk？

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

### @brightdata/sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @brightdata/sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @brightdata/sdk 需要什么版本的 Node\.js？

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

### @brightdata/sdk 可以商用吗？

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

### @brightdata/sdk 的下载量有多少？

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

### @brightdata/sdk 还在维护吗？

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