Skip to main content

​
安装 CLI

运行 Bright Data CLI 最快的方式是使用 npx，它会执行最新版本，无需全局安装：
在本文档的任意命令前加上 npx -p @brightdata/cli 即可以同样的方式运行，无需维护任何全局依赖。Bright Data CLI 需要 Node.js 20 或更高版本。 如果希望获得持久可用的 brightdata 命令和更快的启动速度，请改为全局安装 CLI：
验证全局安装：
快捷别名 bdata 同样可用，既可通过 npx -p @brightdata/cli bdata 使用，也可在全局安装后使用 - 使用您喜欢的任何一个。

​
Windows

通过 npx 运行 CLI 只会完成登录认证，并不会把 brightdata 或 bdata 可执行文件加入 PATH。如果需要长期可用的命令，请全局安装：
在 Windows 上通过 Python 子进程调用 CLI 会报 [WinError 2] The system cannot find the file specified 或 [WinError 193]，因为 npm 安装的是 Python 无法直接执行的 .cmd 包装脚本。三种解决方式：
另外两点 Windows 注意事项：
  • 在默认执行策略下，PowerShell 会阻止 npm 包装脚本。请运行 Get-ExecutionPolicy，若返回 Restricted，可用 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned 允许本地脚本。
  • 控制台默认代码页为 cp1252，当抓取页面包含 UTF-8 内容时会抛出 UnicodeEncodeError。请设置 PYTHONUTF8=1，或在执行命令前运行 chcp 65001。

​
更新 CLI

使用与安装时相同的包管理器升级到最新版本：
将已安装版本与 npm 上发布的最新版本进行对比：
新命令会随 CLI 版本发布。例如，scraper heal 和 scraper approve 在 v0.3.1 中加入。运行上面的更新命令即可获取它们。各版本的变更详情参见发布说明。

​
身份验证

运行登录命令以连接您的 Bright Data 帐户：
这将打开您的浏览器进行安全的 OAuth 身份验证。完成后，CLI 将：
  1. 验证并在本地存储您的 API 密钥
  2. 自动创建所需的代理区域（cli_unlocker、cli_browser）
  3. 设置合理的默认值，以便您立即开始
您只需登录一次。所有后续命令都会自动进行身份验证。

​
替代身份验证方法

当没有可用的浏览器时，使用设备流：
这会打印一个 URL 和一个代码。在任何设备上打开该 URL，输入代码，CLI 即可完成身份验证。
对于 CI/CD 管道或非交互式环境，直接传递您的 API 密钥：
您可以在 Bright Data 控制面板 中找到您的 API 密钥。
设置 BRIGHTDATA_API_KEY 环境变量以完全跳过登录：
CLI 读取的是 BRIGHTDATA_API_KEY，而 Bright Data Python SDK 读取的是 BRIGHTDATA_API_TOKEN。只设置其中一个并期望两者都能工作会静默失败，且不会有任何提示指出缺少哪个变量。如果您在同一环境中同时使用 CLI 和 SDK，请同时导出这两个变量。
这对 Docker 容器、GitHub Actions 和其他自动化环境很有用。

​
交互式设置向导

为了获得引导式的首次体验，请使用 init 命令：
这将逐步引导您完成身份验证、区域选择和默认配置。

​
验证您的设置

登录后，确认一切正常工作：

​
配置存储

CLI 在本地存储凭证和配置： 创建两个文件：
配置的优先级顺序： CLI 标志 → 环境变量 → config.json → 默认值。您始终可以逐个命令覆盖任何设置。

​
后续步骤

命令

探索完整的命令参考。

使用示例

跳转到真实工作流和配方。