使用 Bright Data CLI 构建爬虫

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

前提条件

一个 Bright Data 账户（免费注册，无需信用卡）
一个可使用 npx 的终端（npx 随 Node.js 20 或更高版本一起提供）。任何内嵌终端同样适用：Claude Code、Cursor、Codex、VS Code

使用 npx 运行 Bright Data CLI

无需安装任何东西。通过 npx 按需运行 CLI，它每次都会获取最新版本：

npx -p @brightdata/cli bdata --version

为了让本教程后续的命令保持简短，请为当前 shell 会话设置 bdata 别名。否则，请在下面每个 bdata 命令前加上 npx -p @brightdata/cli：

alias bdata="npx -p @brightdata/cli bdata"

该 CLI 在 npm 上发布为 @brightdata/cli。bdata 和 brightdata 命令可以互换使用。相比 npx 更想要一个持久可用的命令？使用 npm install -g @brightdata/cli 进行全局安装。

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

运行 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 参考。

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

当目标站点改版、爬虫开始返回 null 或缺失字段时，使用 bdata scraper heal 就地修复。自我修复会保留相同的 Collector ID，因此引用该爬虫的每一次触发、调度和集成都能继续工作。流程是：运行、检查、修复（heal）、批准（approve）、重新运行。

修复爬虫

传入 Collector ID 和一句描述问题的自然语言。提示词请保持在 1,000 字符以内。

bdata scraper heal c_mpohus372o5tmid1jk \
  "The points and comment_count fields return null since the site redesign. Re-capture them from the new markup." \
  --url https://news.ycombinator.com

默认情况下，heal 会停在批准关口，让您在修复上线前先审查。

预期结果： 命令返回一个信封对象，其中 status 为 "awaiting_approval"，preview_result 展示所提议修复的示例输出，并附带 next_step 提示告诉您下一步该运行什么命令。

批准或拒绝修复

审查预览。如果无误，批准它。修复会提交到现有爬虫，Collector ID 不变。

bdata scraper approve c_mpohus372o5tmid1jk --url https://news.ycombinator.com

若要放弃所提议的修复并改用更精确的提示词，拒绝它：

bdata scraper approve c_mpohus372o5tmid1jk --reject

预期结果： 批准后，status 推进到 done。拒绝后，爬虫保持不变，您可以用更清晰的提示词重新运行 heal。

重新运行以验证

在同一 URL 上运行修复后的爬虫，确认此前损坏的字段已重新填充。

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

对于无人值守的工作流，在 heal 命令中加上 --auto-approve。它会自动批准修复并一路轮询到 done。仅在您信任该修复、无需人工审查时使用。

常见问题

为什么 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 快速开始。

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

使用 bdata scraper heal 就地修复，它会保留相同的 Collector ID。完整的运行、修复、批准、重新运行流程见上文如何在目标站点变化时修复爬虫？一节。两种替代方案：

控制面板： 使用自我修复工具用自然语言描述修复要求。
直接调用 API： heal 和 approve 命令封装了一个三步循环。POST /dca/collectors/{c_*}/refactor_template 附上提示词，轮询 GET .../refactor_template/progress 直到 status 为 pending_answer，然后 POST .../resume_automation_job 批准或拒绝。参见 Trigger Self-Healing 和 Resume Self-Healing Job。Node.js 实现参见 Scraper Studio 自我修复演示。

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 命令及示例

快速开始

数据提取

Web 访问

AI 训练数据

代理网络

使用 Bright Data CLI 构建爬虫

前提条件

使用 npx 运行 Bright Data CLI

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

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

刚才发生了什么？

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

常见问题

相关内容

使用 AI Agent 构建

Scraper Studio API 快速开始

自我修复工具

Bright Data CLI 概览

​前提条件

​使用 npx 运行 Bright Data CLI

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

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

​刚才发生了什么？

​如何在目标站点变化时修复爬虫？

​常见问题

​相关内容

使用 AI Agent 构建

Scraper Studio API 快速开始

自我修复工具

Bright Data CLI 概览

前提条件

使用 npx 运行 Bright Data CLI

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

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

刚才发生了什么？

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

常见问题

相关内容