> ## Documentation Index
> Fetch the complete documentation index at: https://help.decodo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# pobear：面向终端的网页抓取 CLI

> pobear 是一个开源网页抓取 CLI。它可以爬取站点，用 CSS 选择器或 Markdown 提取数据，保存可复用的任务，并在请求被拦截时回退到 Decodo Web Data API。

[**pobear**](https://github.com/Decodo/pobear) 是一个开源网页抓取 CLI，用于在命令行中提取结构化数据和爬取网站。它以单个 Go 二进制文件的形式在您的终端中运行——无需安装 Python 或 Node.js 运行时——并且将*提取什么*与*如何获取*分离开来。您可以先使用直接请求，无需任何账户。当站点开始拦截您时，只需添加一个参数即可启用代理或 Decodo Web Data API，同时保持相同的提取规则。

> [!NOTE]
>
> 源代码、完整 CLI 参考和最新版本请查看 [**pobear 仓库**](https://github.com/Decodo/pobear)。pobear 采用 MIT 许可证。

## 您可以做什么

* **提取所需字段**：支持属性的 CSS 选择器，或 HTML 转 Markdown。
* **爬取站点**：支持深度、页面数量上限、范围、include/exclude 通配符和请求速率，并支持站点地图发现和 `robots.txt`。
* **保存可复用的任务**：将任意命令输出为 JSON 任务规范，之后可从脚本、调度器或 AI 智能体中再次运行。
* **被拦截时升级**：使用 `--ladder`，pobear 会先尝试直接请求，然后使用您的代理，最后使用 Web Data API。

## 安装

在 Linux 或 macOS 上：

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/Decodo/pobear/main/install.sh | sh
```

pobear 为 Linux、macOS 和 Windows 提供预编译二进制文件，同时支持 x64（amd64）和 ARM64。您无需安装 Go——只有从源码构建时才需要。安装脚本会下载最新版本、校验其校验和，并将 `pobear` 安装到 `$HOME/.local/bin`。在 Windows 上，请从[**发布页面**](https://github.com/Decodo/pobear/releases)下载 `windows_amd64` 或 `windows_arm64` 的 ZIP 包，然后运行 `pobear.exe`。

检查安装结果：

```bash theme={null}
pobear version
```

不带任何参数运行 `pobear`，即可打开交互式终端向导，无需手动输入参数。

## 快速开始

爬取一个示例书店，提取书名和价格，并保存结果。无需账户：

```bash theme={null}
pobear crawl https://books.toscrape.com/ --depth 1 --max-pages 10 \
  --css 'title=h3 a@title' --css 'price=.price_color' --out books.ndjson
```

运行摘要会输出到 stderr：

```text theme={null}
fetched 10, errors 0, skipped 64
```

每个抓取到的页面都会在 `books.ndjson` 中生成一行 NDJSON。`data` 字段保存提取出的值：

```json theme={null}
{
  "url": "https://books.toscrape.com/",
  "tier": "local",
  "status": 200,
  "data": {
    "title": ["A Light in the Attic", "Tipping the Velvet", "..."],
    "price": ["£51.77", "£53.74", "..."]
  }
}
```

`h3 a@title` 读取每个匹配链接的 `title` 属性，`.price_color` 读取元素文本。每条记录还包含 `finalUrl`、`parentUrl`、`depth` 和原始的 `body`。`skipped` 统计的是爬取过程中发现但未访问的链接。

如果不使用 `--out`，记录会以流的方式输出到 stdout，因此您可以将其通过管道传给 `jq` 或其他工具。

## 常见任务

### 以 Markdown 格式获取页面

以干净的 Markdown 打印单个页面，不带 JSON 外层结构。适合作为 LLM 的输入：

```bash theme={null}
pobear scrape https://go.dev/doc/ --extract markdown --bare
```

### 抓取 URL 列表

在文本文件中每行放一个 URL。空行和以 `#` 开头的行会被略过：

```bash theme={null}
pobear scrape urls.txt --extract markdown --out pages.ndjson
```

### 保存并重新运行任务

为任意命令添加 `--print-spec`，即可将其输出为 JSON 任务规范，而不是直接运行：

```bash theme={null}
pobear crawl https://books.toscrape.com/ --depth 1 --max-pages 10 \
  --css 'title=h3 a@title' --css 'price=.price_color' \
  --out books.ndjson --print-spec > books.json
```

需要最新数据时，运行已保存的任务：

```bash theme={null}
pobear run books.json
```

`pobear run` 接受 JSON 或 YAML。您可以把任务文件纳入版本控制，或按计划定时运行。格式说明请参阅[**任务规范参考**](https://github.com/Decodo/pobear/blob/main/docs/JOB_SPEC_REFERENCE.md)。

## 选择获取方式

| 层级 | 参数 | 适用场景 |
| - | - | - |
| 直接请求（`local`） | 默认 | 无防护即可加载的页面。无需账户 |
| 您的代理（`proxy`） | `--proxy '<proxy-url>'` | 需要从其他 IP 发出的请求 |
| Decodo Web Data API（`provider`） | `--provider decodo` | 有反爬虫防护、验证码，或需要 JavaScript 渲染的页面 |

每条记录都有一个 `tier` 字段，标明该记录由哪种方式获取。直接请求和代理请求可以通过 `--profile`（默认 `chrome`）模拟 Chrome、Firefox 或 Safari 的 TLS 指纹，但它们不会执行 JavaScript。

## 使用 Web Data API

1. 从 [**Web Data API 演练场**](https://dashboard.decodo.com/web-data/playground)复制您的 Web Data API 密钥。任意 [**Web Data API 计划**](https://dashboard.decodo.com/web-data/pricing)均可使用，[**控制面板**](https://dashboard.decodo.com/)提供免费试用。
2. 保存密钥。pobear 会提示您输入，并为后续运行保存该密钥：

   ```bash theme={null}
   pobear auth decodo
   ```

   在 CI 或容器中，请改为设置 `POBEAR_PROVIDER_DECODO_TOKEN` 环境变量。
3. 为任意 `scrape` 或 `crawl` 命令添加 `--provider decodo`：

   ```bash theme={null}
   pobear scrape https://books.toscrape.com/ \
     --css 'title=h3 a@title' --css 'price=.price_color' \
     --provider decodo --out books.ndjson
   ```

请求会通过 Web Data API 的 `universal` 目标发出，并使用高级（premium）代理池。JavaScript 渲染默认**关闭**。对于在浏览器中构建内容的页面，请添加 `--render`：

```bash theme={null}
pobear scrape https://quotes.toscrape.com/js/ \
  --css 'quote=.quote .text' --provider decodo --render
```

不使用 `--render` 时，该页面不会返回任何引言；使用之后，10 条全部被提取出来。

使用 `--geo` 和 `--opt name=value` 可设置 Web Data API 参数，例如 `--geo "United States"` 或 `--opt device_type=mobile`。`geo` 的可用取值请参阅[**本地化**](https://help.decodo.com/docs/cn/web-data-api-scrape-localisation.md)。

> [!NOTE]
>
> Web Data API 请求会计入您的 Decodo 计划费用。pobear 本身是免费的。

### 使用目标模板

`--template` 可将 `universal` 切换为专用的 Web Data API 目标。Amazon 的 URL 需要使用 `amazon` 模板——`universal` 目标会以 HTTP `400` 拒绝它们：

```bash theme={null}
pobear scrape 'https://www.amazon.com/dp/B09H74FXNW' \
  --provider decodo --template amazon --geo 10001 --opt parse=true
```

使用 `parse=true` 时，`body` 字段中是解析后的 JSON（标题、价格、品牌、评分等），而不是 HTML。

可用模板：`universal`（默认）、`airbnb`、`amazon`、`apple_app_store`、`autotrader`、`bbb`、`bing`、`google`、`mobile`、`target`、`tiktok`、`tiktok_post` 和 `walmart`。查看每个模板的选项：

```bash theme={null}
pobear providers decodo
```

模板作用于整个任务，因此请把 Amazon URL 和其他站点拆分为不同的任务运行。

> [!WARNING]
>
> * **Amazon 的 geo**：当国家与 Amazon 域名一致时，例如在 amazon.com 上使用 `US`，请改用邮编，例如 `10001`。使用国家代码会返回 HTTP `400`。[了解更多](https://help.decodo.com/docs/cn/web-scraping-api-amazon-geo-parameter.md)
> * **Google 的 geo**：`google` 模板不接受 `--geo`，因此结果可能来自任意国家。若需要特定地区的 Google 结果，请直接调用 Web Data API 的 [**`google_search`**](https://help.decodo.com/docs/cn/web-scraping-api-google-search) 目标。

## 被拦截时自动升级

`--ladder` 会从直接请求开始，只有当请求被拦截、触发速率限制、超时或返回已知的反爬虫挑战页面时，才会升级到下一层级。请与 `--provider decodo` 搭配使用——单独使用 `--ladder` 时没有可升级的目标：

```bash theme={null}
pobear scrape 'https://www.amazon.com/dp/B09H74FXNW' \
  --ladder --provider decodo --template amazon --geo 10001 \
  --css 'title=#productTitle' --css 'price=.a-price .a-offscreen'
```

再加上 `--proxy '<proxy-url>'`，即可在直接请求和 Web Data API 之间先尝试您的代理。能够直接加载的页面永远不会调用该 API，因此您只需为确实需要它的页面付费。

> [!TIP]
>
> 在升级之前，pobear 会在每个层级重试 3 次，每次超时 30 秒。对于您已知有防护的站点，可以跳过升级阶梯，直接使用 `--provider decodo`。等待时间可通过 `--retries` 和 `--timeout` 调整。

## 在 AI 智能体和脚本中使用 pobear

pobear 很适合作为智能体或脚本的子进程使用：

* `pobear docs --json` 以 JSON 形式返回命令、输出格式和退出码。
* `pobear providers decodo --json` 返回每个模板、选项及其默认值。
* 数据以 NDJSON 形式输出到 stdout。运行摘要和错误输出到 stderr。

可以把任务规范直接通过管道传给运行器：

```bash theme={null}
pobear scrape https://books.toscrape.com/ --css 'price=.price_color' \
  --print-spec | pobear run -
```

在使用结果之前，请先检查退出码：

| 退出码 | 含义 |
| - | - |
| `0` | 成功 |
| `1` | 缺少提供商凭据，或凭据被拒绝 |
| `3` | 命令、参数或任务规范无效 |
| `4` | 部分失败——已产出部分结果 |
| `5` | 致命失败——未产出任何可用结果 |

## 故障排查

**摘要中出现 `empty 1`。** 页面已以 HTTP `200` 获取，但您的选择器没有匹配到任何内容。请先检查选择器和页面内容。空结果也可能意味着该页面需要 `--render`，或站点返回了挑战页面。

**在流水线中捕获空提取结果。** 只有当*每一个*抓取到的页面都为空时，`--fail-on-empty` 才会以退出码 `5` 退出。如果一次运行中部分页面提取到了数据、部分没有，仍会以 `0` 退出，因此也请检查摘要中的 `empty` 计数。

**出现 `401` 和 `Missing authorization header`。** 未保存 Web Data API 密钥。请运行 `pobear auth decodo` 或设置 `POBEAR_PROVIDER_DECODO_TOKEN`。

**出现 `400` 和 `Validation failed`。** Web Data API 接受了您的密钥，但拒绝了该请求。最常见的原因是 Amazon 的 URL 没有搭配 `--template amazon`。

## 常见问题

### 如何从终端抓取网站？

安装 pobear，然后运行 `pobear scrape`，传入 URL 和您需要的字段：

```bash theme={null}
pobear scrape https://books.toscrape.com/ --css 'price=.price_color'
```

它会打印一条 NDJSON 记录，其中包含提取出的价格。使用 `pobear crawl` 可在站点内跟踪链接，或者不带参数运行 `pobear` 以打开交互式终端向导。

### 使用 pobear 需要 Decodo 账户吗？

不需要。直接请求无需任何账户。只有在添加 `--provider decodo` 或 `--proxy` 时，您才需要 Web Data API 密钥或代理凭据。

### pobear 能抓取 JavaScript 渲染的网站吗？

直接请求和代理请求不会执行 JavaScript。请使用 `--provider decodo --render`，以获取浏览器渲染完成后的页面。详见上文的"使用 Web Data API"一节。

### pobear 与 Decodo CLI 有什么区别？

两者的默认取向正好相反。[**Decodo CLI**](https://help.decodo.com/docs/cn/cli.md) 是 Web Data API 的 Node.js 客户端：每个请求都经由 Decodo 发出，且每个 Web Data API 目标——搜索引擎、电商、社交媒体——都是一个子命令。pobear 则是一个独立的 Go 二进制文件，默认直接获取页面，只有在您明确要求、或 `--ladder` 遇到拦截时，才会启用代理或 Web Data API。

当您需要带现成目标的完整 Web Data API 时，请使用 Decodo CLI。当您希望用一个二进制文件在无账户的情况下工作、并且只为确实需要的页面付费时，请使用 pobear。

## 相关内容

* [**Decodo CLI**](https://help.decodo.com/docs/cn/cli.md)：官方的 Web Data API 命令行工具，支持搜索、站点地图、爬取和屏幕截图
* [**Web Data API 简介**](https://help.decodo.com/docs/cn/web-data-api-introduction.md)
* [**pobear CLI 参考**](https://github.com/Decodo/pobear/blob/main/docs/CLI_REFERENCE.md)

***

> [card] [支持](https://direct.lc.chat/12092754)
>
> 需要帮助或只是想打个招呼？我们的支持团队全天候为您服务。 \
> 您也可以随时通过电子邮件 [support@decodo.com](mailto:support@decodo.com) 联系我们。

> [card] [反馈](mailto:feedback@decodo.com)
>
> 找不到您要找的内容？请求一篇文章！ \
> 有反馈意见？分享您对我们如何改进的想法。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.