使用 Bright Data CLI 构建爬虫

Bright Data CLI 可在您的终端中通过三条命令构建 Bright Data Scraper Studio 爬虫：先安装，再使用 bdata login 登录，然后运行 bdata scraper create 和 bdata scraper run。本教程将带您端到端构建一个 Hacker News 头条新闻爬虫。该 CLI 在 Claude Code、Cursor 或 Codex 等编码助手的内嵌终端中可原样运行。 预计用时： 约 10 到 25 分钟（AI 生成在后台运行）

前提条件

一个 Bright Data 账户（免费注册，无需信用卡）
Node.js 18 或更高版本（node --version）
一个终端。任何内嵌终端同样适用：Claude Code、Cursor、Codex、VS Code、JetBrains、iTerm

安装 Bright Data CLI

npm install -g @brightdata/cli
bdata --version

该 CLI 在 npm 上发布为 @brightdata/cli。bdata 和 brightdata 命令可以互换使用。

在终端构建您的第一个爬虫

运行 bdata login。CLI 会打开一个浏览器标签页，让您授权访问 Bright Data 账户，然后将 API key 保存到本地。您无需粘贴或复制 key。

bdata login

预期结果：

Opening browser for Bright Data authentication...
Logged in successfully. Key: 2e75****12bf
Checking for required zones...
Zone "cli_unlocker" already exists.
Zone "cli_browser" already exists.

这两个 zone（cli_unlocker 和 cli_browser）是 CLI 运行爬虫时使用的 Web Unlocker API 和 Browser API 端点。Bright Data 会在首次登录时自动创建它们。

创建爬虫

传入一个目标 URL 和一句描述您想要的数据的话。Bright Data 的 AI Agent 会生成输出 schema、编写爬虫代码并返回一个 Collector ID。

bdata scraper create https://news.ycombinator.com \
  "Extract top stories: title, url, points, author, comment count"

AI 流水线分七个阶段实时输出：user_intent_analyzer、planner、collector_maintainer、output_schema_generator、code_generator、input_schema_generator、preview_runner 和 preview_picker。通常耗时 5 到 15 分钟；复杂目标可能需要长达 25 分钟。

预期结果：

Template created: c_mpohus372o5tmid1jk
Triggering AI generation...
Generating scraper...
Step: user_intent_analyzer — polling (attempt 1/600)
...
Done in 280 poll attempts.
{"status":"done","completed_steps":[...],"step":"preview_picker"}

保存 Collector ID（即 c_* 字符串）。它是后续每次运行、调度或 API 调用的稳定句柄。

运行爬虫

传入 Collector ID 和一个 URL。使用 --pretty 美化 JSON 输出。

bdata scraper run c_mpohus372o5tmid1jk https://news.ycombinator.com --pretty

CLI 会先尝试实时模式。如果爬虫触发的页面数超过实时模式允许的上限，CLI 会静默切换到批处理模式（POST /dca/trigger，然后轮询 GET /dca/dataset）继续执行。无需任何参数。

预期结果： 一个 JSON 数组，每条结果对应一行。

[
  {
    "title": "Last.fm is now independent",
    "url": "https://support.last.fm/t/last-fm-is-now-independent/118591",
    "points": 447,
    "author": "twistslider",
    "comment_count": 131
  },
  {
    "title": "DuckDuckGo search saw 28% more visits after Google said people love AI mode",
    "url": "https://www.pcgamer.com/hardware/duckduckgos-ai-free-search-saw-nearly-28-percent-more-visits-in-the-week-following-googles-insistence-that-people-love-ai-mode/",
    "points": 418,
    "author": "HelloUsername",
    "comment_count": 212
  }
]

如何在 Claude Code、Cursor 或 Codex 中使用？

Bright Data CLI 可在任意内嵌终端中原样运行。编码助手本身并不构建爬虫；构建工作由 CLI 调用 Bright Data 的 AI Agent 完成，编码助手只是代您调用 CLI。有两种集成方式让 CLI 在编码助手中更加原生： 在助手的规则文件中固定 Collector ID，让助手在多次会话中复用您的爬虫，而不是每次都重新构建：

CLAUDE.md CODEX.md

SCRAPER_STUDIO_COLLECTOR_ID=c_mpohus372o5tmid1jk
HACKER_NEWS_SCRAPER_USAGE="bdata scraper run $SCRAPER_STUDIO_COLLECTOR_ID <url> --pretty"

通过 brightdata add mcp 将 Bright Data MCP 服务器接入您的助手。MCP 服务器与 Scraper Studio CLI 相互独立，但能为助手提供可直接调用的额外抓取工具（scrape_as_markdown、search_engine 等）：

brightdata add mcp                # 交互式：选择 Claude Code、Cursor 或 Codex

参阅 Bright Data MCP 服务器快速开始了解 MCP 提供的能力。

刚才发生了什么？

三条 CLI 命令对应四个 Bright Data Scraper Studio API 端点。当您准备不通过 CLI 直接集成时，可用下表将 CLI 流程映射到原始 HTTP 调用：

您执行的命令	背后的 Bright Data API 端点
`bdata login`	本地凭据存储。读取来自账户设置的 API key。
`bdata scraper create`	`POST /dca/collector`，随后 `POST /dca/collectors/{c_*}/automate_template`
`bdata scraper run`（输入较少时）	`POST /dca/trigger_immediate`，随后 `GET /dca/get_result`
`bdata scraper run`（输入较多时）	`POST /dca/trigger`，随后轮询 `GET /dca/dataset?id=j_*`

完整的 cURL、Python 和 Node.js 调用示例参见 Bright Data Scraper Studio API 快速开始。完整端点参考参见 Scraper Studio API 参考。

常见问题

为什么 `bdata scraper create` 用了超过 10 分钟？

AI 生成时间取决于目标的复杂度。简单的单页爬虫一般 5 到 10 分钟即可完成；带懒加载、分页或反机器人挑战的页面可能需要 15 到 25 分钟。CLI 每五秒轮询一次 Bright Data 的 AI Flow API 并打印当前阶段，因此您可以让它继续运行，稍后再回来查看。等待期间无需任何操作。

为什么 CLI 在运行中途从实时模式切换到批处理模式？

实时模式对每次请求的页面加载数有上限。当爬虫触发的页面数超过实时模式允许的上限时，CLI 会打印 Realtime page limit exceeded, switching to batch mode...，将相同的输入提交到 POST /dca/trigger，并轮询 GET /dca/dataset?id=j_* 直到快照就绪。此切换是自动的，最终 JSON 数据结构保持一致。页面加载上限请参阅 Scraper Studio 规格说明。

为什么有些行缺少 `points` 或 `comment_count` 字段？

AI Agent 生成的 schema 是逐行尽力而为的，并非严格匹配。Hacker News 上的招聘帖、“Show HN” 帖和非常新的提交并不总是有 points 或评论数，因此爬虫会在该行省略这些字段，而不是编造数值。在您自己的代码中请将缺失字段视为 null。如需强制更严格的 schema，请在 Scraper Studio 中打开该爬虫，或使用自我修复工具重写 schema。

我可以不用 CLI 而从自己的代码触发这个爬虫吗？

可以。bdata scraper create 返回的 Collector ID（c_* 字符串）就是 Bright Data Scraper Studio API 使用的同一个句柄。从任意 HTTP 客户端将它传给 POST /dca/trigger 即可。cURL、Python 和 Node.js 示例参见 Bright Data Scraper Studio API 快速开始。

当目标站点变化时，如何修复爬虫？

自我修复目前还不是 CLI 子命令。您有三种选择：

控制面板： 在 Scraper Studio 中打开爬虫，使用自我修复工具用自然语言描述修复要求。
直接调用 API（三步循环）：
1. POST /dca/collectors/{c_*}/refactor_template，附上修复提示词。
2. 轮询 GET /dca/collectors/{c_*}/refactor_template/progress，直到 status 为 pending_answer 且响应包含所提议的 diff。
3. POST /dca/collectors/{c_*}/resume_automation_job，批准或拒绝该 diff。
参见 Trigger Self-Healing 和 Resume Self-Healing Job。
可运行示例： Scraper Studio 自我修复演示是完整修复循环的 Node.js 实现。

`bdata login` 在没有浏览器的环境（例如 CI）中也能用吗？

bdata login 命令需要浏览器回调。对于无头环境，请将您的 API key 导出为 BRIGHTDATA_API_KEY，CLI 会直接使用它而无需登录步骤：

export BRIGHTDATA_API_KEY="your_api_key_here"
bdata scraper run c_mpohus372o5tmid1jk https://news.ycombinator.com

可从账户设置复制 key。

使用 AI Agent 构建

在 Bright Data 控制面板中构建相同的爬虫，无需打开终端

Scraper Studio API 快速开始

构建完成后，从 cURL、Python 或 Node.js 触发现有爬虫

自我修复工具

当目标站点变化时，用自然语言提示词修复爬虫

Bright Data CLI 概览

每条 bdata 命令及示例

Documentation Index

​前提条件

​安装 Bright Data CLI

​在终端构建您的第一个爬虫

​如何在 Claude Code、Cursor 或 Codex 中使用？

​刚才发生了什么？

​常见问题

​相关内容