brightdata-proxy

Bright Data 代理

为 Bright Data 的四种代理网络生成可用的代码和配置。本技能涵盖使用和集成，不会指导用户完成控制面板 UI 设置。如果用户尚未创建 zone，请告知他们前往 https://brightdata.com 注册，并使用应用内代理创建助手（控制面板会交互式地引导他们选择 zone 类型、池类型并设置凭据——设置应在此处完成，而不是使用本技能）。

快速参考（权威信息）

生成的代码应使用以下值。这些值很容易被错误臆测，请以此为准。

• 代理主机：brd.superproxy.io
• HTTP/HTTPS 代理端口：33335（当前端口，搭配新版 SSL CA 使用——有效期至 2034 年 9 月）
  • 旧端口 22225 适用于旧版 CA（有效期至 2026 年 9 月，已弃用）。除非用户明确说明要使用，否则请使用 33335。
• SOCKS5 端口：22228
• 用户名格式：brd-customer-CUSTOMER_ID-zone-ZONE_NAME，后面可以附加可选的 -key-value 参数（见下文“定向”）。
• 密码：控制面板中的 zone 密码（不是账户密码）。
• 测试端点（用于代码示例，不要用于真实目标）：https://geo.brdtest.com/mygeo.json——以 JSON 格式返回出口 IP、国家/地区、城市和 ASN。
• SSL CA：本技能随附于 assets/brightdata_proxy_ca.crt（Bright Data Proxy Root CA，有效期至 2034 年 9 月）。生成的代码应引用此路径，不要让用户自行下载。如需独立获取，可从 https://brightdata.com/static/brightdata_proxy_ca.zip 下载。

控制面板中的 https://brightdata.com/cp/zones/proxy_examples 会显示适用于每种框架的实时账户专属代码示例；不确定时，请引导用户前往此处获取准确信息。

随附工具（在本技能中）

• assets/brightdata_proxy_ca.crt——Bright Data Root CA。使用它配置 verify=、--cacert、ca: 或 NODE_EXTRA_CA_CERTS，而不是让用户下载证书。
• scripts/smoke_test.sh——基于 cURL 的凭据连通性测试。运行 ./smoke_test.sh CUSTOMER_ID ZONE_NAME ZONE_PASSWORD [COUNTRY] [SESSION_ID]（或设置 BD_CUSTOMER_ID/BD_ZONE/BD_PASSWORD 环境变量）。会自动定位随附的 CA，返回解析后的 JSON 地理信息，并使用不同的退出代码区分身份验证、HTTP 和网络故障。建议用户创建 zone 后首先运行此脚本。
• scripts/proxy_tester.html——单文件浏览器诊断工具。用户使用凭据配置浏览器或操作系统代理，然后在本地打开此文件（或从任意位置托管），即可查看当前出口 IP/地理信息。带有基准保存功能，可直观比较使用代理前后的出口信息。凭据仅保存在 sessionStorage 中——不会上传任何内容。

---

决策 1：选择哪种代理网络？

如果用户没有说明使用哪种网络，只询问一次，然后继续操作。快速判断标准：

网络	推荐场景
数据中心	成本最低、速度最快。适用于未受保护的目标（新闻网站、公共 API、轻量级抓取、低规模账户管理，以及在限制宽松的网站上绕过地理限制）。
ISP	对目标网站而言看起来像住宅网络的静态 IP。最适合长时会话、受保护平台上的账户管理，以及 IP 信誉重要但同时需要速度和稳定性的场景。
住宅	来自 1 亿多个 IP 池的真实用户 IP。当数据中心和 ISP 代理被封锁时的默认选择。在难以访问的目标上成功率最高。按 GB 付费；速度较慢。需要 SSL 证书或 KYC（见下文“住宅/移动网络访问”）。
移动	3G/4G/5G 移动运营商 IP。成本最高。仅在目标限制极严时使用（Instagram、TikTok、部分银行）。网络访问要求与住宅代理相同。

用户不确定时的默认选择顺序：数据中心 → 住宅。ISP 和移动代理是针对特定需求的主动选择。

决策 2：选择哪种 IP 池类型？（Datacenter 和 ISP）

Bright Data 提供 Datacenter 和 ISP 流量，有三种 IP 分配模式。用户在控制面板中创建区域时选择模式。

池类型	定义	推荐使用场景
共享池（也称为“按 GB 付费”或“无限量”）	从大型共享池中提取随机 IP。不分配固定 IP。按流量 GB 数付费。	高流量轮换式抓取的默认选择。无需指定 IP，只需频繁获取新 IP。
共享 IP	租用一组固定的 N 个 IP，但与其他 Bright Data 客户共享。比专用 IP 便宜。	中等预算。需要一定的 IP 稳定性，但不要求独占。适用于目标网站接受温热程度适中的 IP 的情况。
专用 IP	租用一组固定的 N 个 IP，专供你使用。其他客户无法使用这些 IP。单个 IP 的成本最高。	在会严格识别 IP 特征的平台上进行账户管理；任何需要由你掌控良好信誉的场景；以及共享 IP 上其他客户的不当行为可能连累你的场景。

对于 Residential 和 Mobile，与“专用”对应的是通过 -gip- 参数选择的专用 gIP（IP 组），这与 DC/ISP 专用 IP 并不相同。请勿混淆。

---

代理 URL 格式与身份验证

用户名包含每个请求的所有配置。通用格式如下：

brd-customer-CUSTOMER_ID-zone-ZONE_NAME[-param1-value1][-param2-value2]...

组合成代理 URL 后如下所示：

http://brd-customer-CUSTOMER_ID-zone-ZONE_NAME[-PARAMS]:[email protected]:33335

注意：

• 即使目标使用 HTTPS，协议也应为 http://——这是代理自身的协议，而非目标地址的协议。
• 如果密码包含特殊字符，请始终对密码进行 URL 编码。
• 参数以连字符附加到用户名上——它们不是 URL 上的查询字符串参数。
• 创建后无法更改区域名称；如果用户想使用不同名称，必须新建区域。

用户名参数（定向、轮换、会话）

参数	适用范围	作用	用户名后缀示例
-country-XX	所有网络	ISO 国家代码（2 位小写字母）。eu = 随机选择一个欧盟国家。	-country-us
-state-XX	仅限 Residential、Mobile	美国州，2 个字母；需要 -country-us	-country-us-state-ny
-city-NAME	仅限 Residential、Mobile	城市名称，不含空格（sanfrancisco）；需要指定国家	-country-us-city-sanfrancisco
-zip-NNNNN	仅限 Residential、Mobile	美国邮政编码，5 位数字	-country-us-zip-37501
-asn-NNNNN	仅限 Residential、Mobile	定向到特定 ASN	-asn-56386
-os-X	仅限 Residential	windows、macos、android	-os-windows
-carrier-X	仅限 Mobile	指定运营商（例如 -carrier-dt）	-carrier-dt
-session-STRING	全部	粘性会话——相同的会话 ID 在会话有效期内会返回同一个出口 IP。为每个逻辑上的“用户会话”使用随机字符串来实现轮换。	-session-abc12345
-ip-A.B.C.D	仅限具有专用 IP的区域	固定使用某个已分配的 IP	-ip-1.2.3.4
-gip-NAME	仅限专用 Residential 或 Mobile	固定使用某个 gIP 组	-gip-us_7922_fl_hollywood_0
-dns-local / -dns-remote	全部	remote = 在代理对端解析 DNS（Residential 的默认值）；local = 在 super proxy 上解析	-dns-remote
-const	Residential、Mobile	绑定到同一对端；如果对端不可用，则返回 502“no peer available”，而不是切换对端	-const
-direct	全部	强制由 super proxy 本身发出请求（跳过对端路由）。很少需要使用。	-direct
-c_tag-VALUE	全部	在响应标头中回传自定义标签，用于大规模关联请求与响应	-c_tag-job42-row7

重要限制：Datacenter 和 ISP 区域仅支持按国家定向。州、城市、邮政编码、ASN、操作系统和运营商定向仅适用于 Residential/Mobile。不要生成在 DC 或 ISP 区域中使用 -city- 的代码——这会静默失败或返回 400。

会话与轮换模式

• **想让每个请求都使用新的 IP？**省略 -session-。超级代理会在每个请求中为你分配新的对等节点。
• **想在多步骤流程（登录 → 操作 → 操作）中保持相同的 IP？**生成一个随机的 session_id 并重复使用：-session-{session_id}。新值 = 新 IP。
• 空闲会话超时（根据 Bright Data 文档，空闲时间过长会丢失 IP）：数据中心约 1 分钟，住宅约 5 分钟，ISP 约 7 分钟，移动网络约 10 分钟。对于超出超时时间的流程，请发送保活请求，或接受 IP 会轮换这一情况。
• 最大程度的控制：使用专用 IP 区域 + -ip-A.B.C.D，将每个请求固定到特定的已分配 IP。没有随机性。

---

核心代码模式

cURL（用于测试/调试）

curl --proxy brd.superproxy.io:33335 \
  --proxy-user 'brd-customer-CUSTOMER_ID-zone-ZONE_NAME:ZONE_PASSWORD' \
  --cacert ./assets/brightdata_proxy_ca.crt \
  'https://geo.brdtest.com/mygeo.json'

（对于数据中心和 ISP 区域，--cacert 标志可选。对于住宅和移动网络则必须使用，除非用户已在系统中安装 CA 或完成 KYC——请参阅下文“住宅与移动网络访问”。）

若要完全绕过证书验证（仅当用户选择“忽略 SSL 错误”方案时才可使用）：

curl -k --proxy brd.superproxy.io:33335 \
  --proxy-user 'brd-customer-CUSTOMER_ID-zone-ZONE_NAME:ZONE_PASSWORD' \
  'https://geo.brdtest.com/mygeo.json'

Python — requests

import requests

CUSTOMER_ID = "your_customer_id"
ZONE_NAME = "your_zone_name"
ZONE_PASSWORD = "your_zone_password"

proxy_user = f"brd-customer-{CUSTOMER_ID}-zone-{ZONE_NAME}"
proxy_url = f"http://{proxy_user}:{ZONE_PASSWORD}@brd.superproxy.io:33335"

proxies = {"http": proxy_url, "https": proxy_url}

# Preferred: verify TLS using the bundled Bright Data CA
resp = requests.get(
    "https://geo.brdtest.com/mygeo.json",
    proxies=proxies,
    verify="./assets/brightdata_proxy_ca.crt",  # path to bundled cert
    timeout=30,
)
print(resp.json())

国家/地区定位：

proxy_user = f"brd-customer-{CUSTOMER_ID}-zone-{ZONE_NAME}-country-us"

粘性会话（按逻辑用户轮换，会话内使用相同 IP）：

import secrets
session_id = secrets.token_hex(8)
proxy_user = f"brd-customer-{CUSTOMER_ID}-zone-{ZONE_NAME}-country-us-session-{session_id}"

在多个请求之间轮换——为每个请求分配各自的会话 ID：

import secrets, requests

def proxy_for_request():
    sid = secrets.token_hex(8)
    user = f"brd-customer-{CUSTOMER_ID}-zone-{ZONE_NAME}-session-{sid}"
    url = f"http://{user}:{ZONE_PASSWORD}@brd.superproxy.io:33335"
    return {"http": url, "https": url}

for target in targets:
    requests.get(target, proxies=proxy_for_request(), verify=CA_PATH, timeout=30)

Node.js — undici / fetch（Node 18+）

import { fetch, ProxyAgent } from 'undici';

const CUSTOMER_ID = 'your_customer_id';
const ZONE_NAME = 'your_zone_name';
const ZONE_PASSWORD = 'your_zone_password';

const proxyUser = `brd-customer-${CUSTOMER_ID}-zone-${ZONE_NAME}`;
const proxyUrl = `http://${proxyUser}:${ZONE_PASSWORD}@brd.superproxy.io:33335`;

const agent = new ProxyAgent(proxyUrl);

const res = await fetch('https://geo.brdtest.com/mygeo.json', { dispatcher: agent });
console.log(await res.json());

要在 Node 上验证 CA，请在环境中设置 NODE_EXTRA_CA_CERTS=/path/to/brightdata_proxy_ca.crt，或传入一个设置了 ca 的自定义 Agent。若要绕过证书检查（最后手段）：NODE_TLS_REJECT_UNAUTHORIZED=0。

Node.js — axios with https-proxy-agent

import axios from 'axios';
import { HttpsProxyAgent } from 'https-proxy-agent';

const proxyUrl = `http://brd-customer-${CUSTOMER_ID}-zone-${ZONE_NAME}:${ZONE_PASSWORD}@brd.superproxy.io:33335`;
const agent = new HttpsProxyAgent(proxyUrl);

const res = await axios.get('https://geo.brdtest.com/mygeo.json', {
  httpAgent: agent,
  httpsAgent: agent,
  proxy: false, // important: tell axios to use our agent, not its own proxy logic
});
console.log(res.data);

有关框架集成（Playwright、Puppeteer、Selenium、Scrapy、httpx、aiohttp）和其他模式，请参阅 references/code-templates.md。

---

住宅与移动网络访问

住宅和移动网络有一项数据中心和 ISP 不具备的网络访问策略。在针对任意 HTTPS 目标发出请求并使其成功之前，用户必须从以下三种方式中选择一种：

1. 使用 Bright Data CA 证书（首选——大多数用户都应采用此方式）。此证书已随此技能一同打包，位于 assets/brightdata_proxy_ca.crt。有两种应用方式：
   • 在代码中加载，用于每个请求（无需安装到系统中）。对于 Python requests：verify="./assets/brightdata_proxy_ca.crt"。对于 cURL：--cacert ./assets/brightdata_proxy_ca.crt。对于 Node：设置 NODE_EXTRA_CA_CERTS=./assets/brightdata_proxy_ca.crt 环境变量，或传入一个设置了 ca 的自定义 Agent。这是最简洁的方案，也是我们默认推荐在生成的代码中采用的方式。
   • 在系统中安装证书（Windows / macOS 钥匙串 / Linux update-ca-certificates / iOS / Android）。当使用不提供 CA 证书选项的第三方工具时，需要采用此方式。将随附的 assets/brightdata_proxy_ca.crt 复制到相应的信任存储区，然后重启应用。如果用户希望自行获取，也可使用公共镜像：https://brightdata.com/static/brightdata_proxy_ca.zip。
2. KYC 验证。在 Bright Data 控制面板中提交身份验证。获批后，原生代理访问不再需要证书。
3. 忽略 SSL 错误（最后手段，不建议用于生产环境）。在 Python 中：requests.get(..., verify=False)。在 Node 中：rejectUnauthorized: false 或 NODE_TLS_REJECT_UNAUTHORIZED=0。在 cURL 中：-k。此方式可行，但会失去抵御中间人攻击（MITM）的端到端加密保障——用于临时测试尚可，但不适用于任何会处理凭据或个人身份信息（PII）的场景。

为住宅/移动网络生成代码时，默认应采用方案 1a（在代码中加载 CA），并将证书路径设为由用户填写的占位符。简要提及方案 2 和 3 作为替代方案。

对于数据中心和 ISP，无需采用以上任何方式——它们不执行网络访问策略。

---

测试与调试

在抓取真实目标之前，请先确认代理可正常工作。以下两个内置工具可覆盖完整流程：

1. 命令行冒烟测试 — scripts/smoke_test.sh：

./scripts/smoke_test.sh CUSTOMER_ID ZONE_NAME ZONE_PASSWORD
# with optional country and sticky session:
./scripts/smoke_test.sh CUSTOMER_ID ZONE_NAME ZONE_PASSWORD us my-session-1

# or via env vars:
BD_CUSTOMER_ID=xxx BD_ZONE=yyy BD_PASSWORD=zzz ./scripts/smoke_test.sh

该脚本通过相应区域访问 geo.brdtest.com/mygeo.json，并返回解析后的 JSON（IP、国家/地区、城市、ASN）。退出代码会区分身份验证失败（2）和 HTTP 错误（3），因此也适合在脚本中调用。

2. 浏览器诊断 — scripts/proxy_tester.html：

在浏览器中打开该文件。它会持续轮询地理位置端点，并显示出口 IP、国家/地区、城市和 ASN。填写区域凭据后，它会生成可直接粘贴到浏览器或操作系统代理设置中的准确代理配置字符串。“Save as baseline”按钮会记录启用代理前的 IP，便于直观确认代理是否生效（状态会变为绿色，并显示前后变化）。当需要向团队成员说明代理正在工作，或调试“我的浏览器是否真的通过代理访问”这类问题时，这个工具很有用。

需要临时执行单行命令时，也可以直接使用原始 cURL：

curl --proxy brd.superproxy.io:33335 \
  --proxy-user 'brd-customer-CUSTOMER_ID-zone-ZONE_NAME:ZONE_PASSWORD' \
  --cacert ./assets/brightdata_proxy_ca.crt \
  'https://geo.brdtest.com/mygeo.json'

预期结果：包含 ip、country、asn、geo 的 JSON。如果看到该结果，说明身份验证和路由均正常。不要直接通过代理网络测试 Google、Bing 或其他搜索引擎——Bright Data 会阻止代理网络直接访问搜索引擎。请改用 SERP API。

常见错误及其含义（高价值子集）：

• 407 Proxy Authentication Required：用户名结构错误，或区域密码错误。请仔细检查 brd-customer- 前缀和 -zone- 部分。客户 ID 来自控制面板，而不是你的邮箱。
• 502 "no peer available"：通常是因为 -const 或 -ip- 指定的 IP 已离线。移除 -const，或改用其他 IP。
• 目标端返回 403（而非 Bright Data 返回）：目标屏蔽了该代理 IP。请尝试使用 Residential、添加粘性会话、降低请求频率，或使用 Web Unlocker API。
• Residential/Mobile 出现 TLS / 证书错误：你跳过了网络访问设置。请安装证书（或在代码中加载证书），也可以暂时使用 verify=False。
• DC/ISP 的定向设置被静默忽略：你在 DC/ISP 区域中使用了 -city- 或 -state-。这些区域只支持 -country-。

如果遇到上文未涵盖的 Bright Data 特定错误代码，请在完整目录中查询：https://docs.brightdata.com/proxy-networks/errorCatalog。检查响应头以获取准确代码——Bright Data 正在从旧版 x-brd-err-code 标头迁移到 RFC 9209 标准的 Proxy-Status 标头，因此生成的调试代码应同时检查两者。代码采用 category_number 格式，可一眼看出故障所在层级：client_*（身份验证或请求格式，例如 client_10000）、policy_*（Bright Data 策略拦截，例如 policy_20050）、target_*（目标端故障，例如 target_40011）等。

---

用户尚未设置区域时

不要尝试编写控制面板操作流程的脚本，也不要调用账户管理 API 为用户创建区域——这些流程需要交互，且因账户而异。请改为告知用户：

请在 https://brightdata.com 注册（新账户可获 2 美元试用额度，有效期为 7 天；添加付款方式后，还可获 5 美元奖励，有效期为 30 天——请注意，代理产品单独计费，不包含在每月免费额度中）。登录后，点击 Proxies & Scraping → Add，应用内助手会引导你选择网络、池类型并为区域命名。完成后，从区域概览页面复制客户 ID、区域名称和区域密码，并粘贴到这里——我会为你生成代码。

控制面板的 proxy_examples 页面（https://brightdata.com/cp/zones/proxy_examples）也提供多种语言和框架的实时账户专属代码片段——如果你觉得本技能中的内容可能已过时，可以将其用作核验。

---

参考文件

• references/code-templates.md — Playwright、Puppeteer、Selenium（现代身份验证扩展方法 + SeleniumWire 备用方案）、Scrapy、httpx、aiohttp 的完整可运行代码，以及几种语言的变体。当用户询问上述内容未涵盖的特定框架时，请阅读此文件。
• references/troubleshooting.md — 扩展的错误目录和调试方法。当用户报告错误或意外行为时，请阅读此文件。
• assets/brightdata_proxy_ca.crt — Bright Data 代理根 CA（端口 33335，2034 年 9 月到期）。在任何使用住宅或移动区域的生成代码中引用此路径。
• scripts/smoke_test.sh — cURL 凭据冒烟测试（参见“测试”部分）。
• scripts/proxy_tester.html — 单文件浏览器诊断工具（参见“测试”部分）。