📦 Bright Data Best Practices — Bright Data 最佳实践

v1.0.0

构建可直接用于生产的 Bright Data 集成，内置最佳实践。为使用编程助手（Claude Code、Cu...）的开发者提供参考文档。

0· 19·0 当前·0 累计

by @meirk-brd (Meir Kadosh)

开发工具代码生成文档工具数据分析数据可视化

下载技能包

安全扫描

VirusTotal

可疑

查看报告

OpenClaw

安全

medium confidence

该技能是 Bright Data API 的文档/参考包，其说明与示例均服务于该目的，但包元数据未声明文档所引用的环境凭据——使用前请检查凭据处理。

评估建议

本包是 Bright Data 的文档/参考 skill，内部逻辑与该用途一致。安装或允许其自主运行前，请注意： 1）凭据处理——文档提到 BRIGHTDATA_API_KEY、BROWSER_AUTH 及 zone 密码，但 registry 元数据未声明任何必需 env var；仅在了解 agent 如何使用凭据时才提供，优先使用限定/临时 API key，测试后轮换。 2）尽量使用厂商 CLI 登录（bdata login），而非将长期 API key 嵌入 env var 或文件。 3）慎用异步/webhook/输出功能——它们可能将抓取数据发往外部 URL 或云存储（S3/GCS）；启用前验证 webhook URL 及存储配置。 4）监控网络活动与账单（Bright Data 服务计费）；尽可能为 key 设置配额/过期时间。 5）若不信任 skill 所有者（来源未知、无主页），先审查其将执行的确切 agent 提示/交互，验证来源前勿授予宽泛凭据。...

详细分析 ▾

✓ 用途与能力

名称与所含内容相符：涵盖全面的 Bright Data API/CLI 参考（Web Unlocker、SERP API、Web Scraper API、Browser API）。文件中的示例和参数与面向开发者的最佳实践指南保持一致；注册表中请求的 binaries/envs 极少（无），但内容确实合理讨论了 Bright Data 凭据与 CLI 用法。

ℹ 指令范围

SKILL.md 及其引用的文档提供了示例代码、CLI 用法、环境变量模式以及 Bright Data CLI 凭据路径（~/.config/brightdata-cli/... 等）。说明并未要求代理扫描无关系统文件或调用意外的外部端点：所有网络端点均为 Bright Data 域名（api.brightdata.com、brd.superproxy.io）。文档确实展示了用于异步作业的 webhook/notify 和外部存储（S3/GCS）选项——这些在生产流程中属合法功能，但值得注意，因为若配置不当，可能导致数据被推送到第三方端点。

✓ 安装机制

仅含指令、无安装配置且无代码文件——安装风险最低。文档中列出的 CLI 安装路径（npm install -g @brightdata/cli、curl 安装器、npx）均为该厂商标准方式；本 skill 本身不执行任何安装。

⚠ 凭证需求

文档明确引用了多种密钥与凭据格式（BRIGHTDATA_API_KEY、BRIGHTDATA_UNLOCKER_ZONE、BRIGHTDATA_SERP_ZONE、BROWSER_AUTH、zone 密码、proxy username 字符串）。然而，registry 元数据未列出任何必需的环境变量或主要凭据。这种不匹配带来可用性/安全隐患：skill 会要求或指示使用密钥，却未预先声明。请仅提供适当作用域/临时的 Bright Data 密钥，并清楚凭据将用于何处（CLI 或直接 REST/proxy）。

✓ 持久化与权限

always: false 且 disable-model-invocation: false（默认）——技能未被强制包含，可由代理自主调用（正常）。该技能不会请求持久化系统级更改，也不会访问其他技能的配置。

安全有层次，运行前请审查代码。

运行时依赖

无特殊依赖

安装命令

点击复制

官方npx clawhub@latest install brightdata-bright-data-best-practices

镜像加速npx clawhub@latest install brightdata-bright-data-best-practices --registry https://cn.longxiaskill.com

技能文档

CLI 设置参考安装、认证与故障排查的权威文档统一在 → references/cli-setup.md；任何调用 bdata 的任务前请先查阅。

Bright Data APIs Bright Data 提供大规模网页数据提取基础设施。四大核心 API 覆盖不同场景——永远选最专精的工具。

认证模式（所有 API 通用）以下环境变量用于直接 REST 集成；若用 bdata CLI，执行 bdata login 会自动处理（见 references/cli-setup.md）。 export BRIGHTDATA_API_KEY="your-api-key" # 控制面板 > 账户设置 export BRIGHTDATA_UNLOCKER_ZONE="zone-name" # Web Unlocker 区域名 export BRIGHTDATA_SERP_ZONE="serp-zone-name" # SERP API 区域名 export BROWSER_AUTH="brd-customer-ID-zone-NAME:PASSWORD" # Browser API 凭证

Web Unlocker & SERP API 请求头： Authorization: Bearer YOUR_API_KEY

Web Unlocker API HTTP 型抓取代理，最适合无浏览器交互的简单页面获取。 Endpoint: POST https://api.brightdata.com/request

示例： import requests response = requests.post( "https://api.brightdata.com/request", headers={"Authorization": f"Bearer {API_KEY}"}, json={ "zone": "YOUR_ZONE_NAME", "url": "https://example.com/product/123", "format": "raw" } ) html = response.text

关键参数 zone: 区域名（必填） url: 目标 URL，需含 http:// 或 https://（必填） format: "raw"(HTML) 或 "json"（结构化包装）（必填） method: HTTP 方法，默认 "GET" country: 2 位 ISO 国家码，如 "us"、"de" data_format: 转换输出，"markdown" 或 "screenshot" async: true 启用异步模式

速用模式 # 获取 markdown（适合喂给 LLM） json={"zone": ZONE, "url": url, "format": "raw", "data_format": "markdown"}

# 德国定位 json={"zone": ZONE, "url": url, "format": "raw", "country": "de"}

# 截图调试 json={"zone": ZONE, "url": url, "format": "raw", "data_format": "screenshot"}

# 异步批量 json={"zone": ZONE, "url": url, "format": "raw", "async": True}

铁律：禁止将 Web Unlocker 与 Puppeteer、Playwright、Selenium 或任何反检测浏览器混用；请改用 Browser API。完整参考见 references/web-unlocker.md（含代理接口、特殊头、异步流程、功能、计费）。

SERP API 结构化提取 Google、Bing、Yandex、DuckDuckGo 搜索结果。 Endpoint: POST https://api.brightdata.com/request（同 Web Unlocker）

示例： response = requests.post( "https://api.brightdata.com/request", headers={"Authorization": f"Bearer {API_KEY}"}, json={ "zone": "YOUR_SERP_ZONE", "url": "https://www.google.com/search?q=python+web+scraping&brd_json=1&gl=us&hl=en", "format": "raw" } ) data = response.json() for result in data.get("organic", []): print(result["rank"], result["title"], result["link"])

Google 关键参数 q: 查询词，如 q=python+web+scraping brd_json: 返回解析 JSON，固定 brd_json=1（数据管道必带） gl: 国家，如 gl=us hl: 语言，如 hl=en start: 翻页偏移，start=10（第 2 页） tbm: 搜索类型，tbm=nws(新闻)/isch(图片)/vid(视频) brd_mobile: 设备，brd_mobile=1 或 ios brd_browser: 浏览器，如 chrome brd_ai_overview: 触发 AI 摘要，brd_ai_overview=2 uule: 编码后的精确地理位置

注：num 参数已于 2025 年 9 月废弃，翻页请用 start。

解析后 JSON 结构 { "organic": [{"rank":1,"global_rank":1,"title":"...","link":"...","description":"..."}], "paid":[], "people_also_ask":[], "knowledge_graph":{}, "related_searches":[], "general":{"results_cnt":1240000000,"query":"..."} }

Bing 关键参数 q: 查询词 setLang: 语言（建议 4 位，如 en-US） cc: 国家码 first: 翻页（步长 10：1,11,21…） safesearch: off / moderate / strict brd_mobile: 设备类型

异步批量 SERP # 提交

数据来源：ClawHub ↗ · 中文优化：龙虾技能库