mcpField
S
scraperapi-scraper-builder

scraperapi-scraper-builder

github.com/scraperapi开发10106 次安装12 周前更新
代码仓库

关于 scraperapi-scraper-builder

用于借助 ScraperAPI 构建可运行爬虫的工作流 Skill。它从需求收集和页面探查入手，再依据观察结果选择架构并生成代码。

主要功能

  1. 01收集爬取需求
  2. 02探查目标页面
  3. 03依据证据选择架构
  4. 04生成 Python 和 Node.js 脚本
  5. 05提供额度预算与重试指导

适用场景

  1. 01为目标网站创建爬虫
  2. 02选择渲染和代理设置
  3. 03处理分页与大量 URL

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/scraperapi/scraperapi-skills --skill scraperapi-scraper-builder

安装后在 Claude Code 中输入/scraperapi-scraper-builder确认已加载。

附带文件references/code-templates.md

详细介绍

ScraperAPI 爬虫构建器

使用 ScraperAPI 构建可用于生产环境的爬虫。分四个阶段进行：收集需求、探查目标网站、制定架构决策，然后生成完整且可运行的脚本。

阶段 1 — 收集需求

编写代码前，收集以下信息。优先从用户的提示中提取；只询问缺失的信息。

信息未指定时的默认值
目标 URL 或网站必填 — 如果缺失则询问
要提取的数据字段如果含糊不清则询问（“产品信息” → 具体是哪些字段？）
数据量推断：单个 URL / 分页 / URL 批量列表
语言如果无法从上下文判断则询问；Python 是合理的默认选择
输出格式stdout JSON
是否需要地理定位？根据网站类型推断；电商定价时需确认

阶段 2 — 网站侦察

在做出任何架构决策之前，使用 ScraperAPI 获取目标网站的 1–2 个示例页面，以观察实际行为。这能用证据替代猜测，最多消耗 2 个点数。

获取内容

最多获取两个页面：

  1. 列表页或分类页（主要目标）——例如产品网格、搜索结果或文章索引
  2. 详情页（仅当用户需要单个条目的数据时）——例如单个产品、文章或个人资料

始终从标准请求开始（不使用 render 或 premium）——这是成本最低的探测方式：

GET https://api.scraperapi.com/?api_key=<SCRAPERAPI_API_KEY>&url=<target_url>
观察内容

1. 响应状态

状态含义
200继续进行内容分析
403 + 正文包含 "Just a moment"、cf-ray 或 "Cloudflare"检测到 Cloudflare
403 + 正文包含 "DataDome"、"PerimeterX" 或 "Akamai"检测到机器人管理系统
403（通用）存在反机器人保护；可能需要高级代理
429请求频率受限；在架构阶段记录

2. 内容完整性（针对 200 响应）

以下信号表明需要使用 render=true：

  • SPA 容器为空：<div id="root"></div>、<div id="app"></div>、<div id="__next"></div> 且没有子元素
  • <script> 标签中包含框架标记：_next、__nuxt__、react、vue、angular
  • 响应大多由 <script> 和 <div> 标签组成，可见文本很少
  • HTML 中缺少阶段 1 指定的目标数据字段

如果原始 HTML 中明显包含目标数据 → 标准渲染已足够，不要启用 render。

3. 分页结构

查看 <a> href 和链接标签中的网站分页方案：

  • <a rel="next"> 或 <link rel="next"> → 跟随下一链接模式
  • href 中包含 ?page=N、?p=N、/page/N/ → 页码分页
  • ?start=N 或 ?offset=N → 基于偏移量的分页
  • 没有分页链接，但有 data-infinite-scroll 或“Load more”按钮 → 由 JS 驱动的无限滚动（需要 render=true）

记录确切的 URL 模式——这将直接用于阶段 4 的分页循环。

4. 数据结构（目标字段可见时）

  • 找出重复出现的容器元素（例如 <li class="product-item">、<div class="listing-card">）
  • 记录阶段 1 中每个目标字段的 CSS 选择器
  • 检查内嵌结构化数据：<script type="application/ld+json">（JSON-LD）或 data-* 属性——解析这些数据通常比解析原始 HTML 更简洁

5. 内部 API 端点（额外信息）

扫描内联 <script> 块，查找指向内部路径（例如 /api/products、/_next/data/）的 fetch( 或 axios.get( 调用。如果找到，爬取该 JSON 端点通常比解析 HTML 更简单、更稳定。

网站概况 — 本阶段的输出

继续之前，先用表格总结调查结果。每一行都对应阶段 3 中的一个具体决策。

| Signal                  | Observed                              |
|-------------------------|---------------------------------------|
| HTTP status (standard)  | 200 / 403 / ...                       |
| Anti-bot protection     | None / Cloudflare / DataDome / ...    |
| JS rendering needed     | Yes / No / Uncertain                  |
| Pagination pattern      | ?page=N / rel=next / load-more / ...  |
| Target data visible     | Yes / No (skeleton HTML)              |
| Data container selector | e.g. div.product-card                 |
| Structured data (LD+J)  | Present / Not found                   |
| Internal API detected   | Yes (<path>) / No                     |

阶段 3 — 架构决策

将阶段 2 的网站概况作为每项决策的主要依据。按顺序完成全部六项决策，并引用概况中的具体观察结果。编写代码前，先用表格总结所有决策（参见本节末尾）。

决策 1 — 是否有结构化数据端点？

检查目标网站是否属于受支持的垂直领域。如果是，请使用该端点——结构化端点会返回干净的 JSON，无需解析 HTML，并且会自动处理渲染和反机器人机制。跳过决策 2 和 3。

受支持的垂直领域（请对照 文档确认）：

  • Amazon：product、search、offers、reviews
  • Google：search、news、jobs、shopping、maps
  • Walmart：product、search、category
  • eBay：product、search
  • Redfin：listing、search
  • Indeed：jobs、job
  • LinkedIn：profile、jobs（可用性可能有所不同）

端点格式：GET https://api.scraperapi.com/structured/<site>/<type>?api_key=...&<required_param>=...

决策 2 — 页面是否需要 JavaScript 渲染？

仅当站点配置文件确认目标数据在标准响应中缺失时，才启用 render=true。费用：约 10 个积分/请求。

  • 站点配置文件显示“目标数据可见：否”或“需要 JS 渲染：是” → 启用 render=true
  • 站点配置文件显示“目标数据可见：是” → 不要启用 render=true
  • 站点配置文件显示“不确定” → 再使用 render=true 获取一个样本并进行比较

不要臆测性地启用 render=true——第 2 阶段的探测结果才是依据。

决策 3 — 网站是否有反机器人保护？

以站点配置文件中的“反机器人保护”行作为起点。逐步升级——绝不要一开始就使用最高级别。

  • 站点配置文件显示“无” → 从标准模式开始
  • 站点配置文件显示“Cloudflare”或任何机器人管理器 → 从 premium=true 开始（约 10 个积分）
  • premium=true 仍返回 403 → 升级到 ultra_premium=true（约 30 个积分）

ultra_premium=true 和 premium=true 互斥——绝不要同时设置。

决策 4 — 数据量是多少？
数据量方式
1–10 个 URL同步循环，无需特殊处理
10–100 个 URL同步处理，并限制为每秒 1 个请求
>100 个 URL异步 Jobs API（POST https://async.scraperapi.com/batchjobs）

对于异步批次，脚本会提交所有 URL，然后轮询，直到所有任务完成。异步处理模式请参阅 references/code-templates.md。

决策 5 — 是否需要会话状态？

以下情况请添加 session_number=<int>：

  • 爬虫必须遵循登录流程
  • 多步骤结账或需要身份验证的页面
  • 必须在多个请求间保持分页状态

会话 ID 可以使用任意整数。具有相同 session_number 的请求会通过同一个代理 IP 路由。

决策 6 — 是否需要地理定位？

以下情况请添加 country_code（ISO-3166，例如 us、gb、de）：

  • 抓取因地区而异的价格
  • 目标网站根据地理位置重定向或拦截请求
  • SERP 结果需要本地化
架构摘要表

生成代码前，请打印此表：

| Parameter      | Value      | Reason                            |
|----------------|------------|-----------------------------------|
| url            | ...        | target                            |
| render         | true/false | (why)                             |
| premium        | true/false | (why)                             |
| ultra_premium  | true/false | (why)                             |
| country_code   | us / –     | (why)                             |
| session_number | N / –      | (why)                             |
| volume mode    | sync/async | (why)                             |

第 4 阶段 — 生成代码

如果尚未确定语言，请询问（默认：Python）。生成一个完整、可运行的脚本，而非伪代码或代码片段。请参阅 references/code-templates.md，了解可供修改的基础模板。

使用第 2 阶段的站点配置文件预先填充解析逻辑：如果已识别出数据容器选择器（例如 div.product-card），请直接将其写入 extract() 函数，而不要留下 TODO。如果发现了 JSON-LD，请解析 <script type="application/ld+json">，而不是遍历 HTML 树。如果发现了内部 API 路径，请改为请求该端点，而不是页面 HTML。

Python 脚本结构
  1. 使用 argparse 构建 CLI，包含 --url、--pages、--output、--max-credits，以及 Phase 3 中确定的所有 ScraperAPI 参数对应的标志
  2. 从 os.environ["SCRAPERAPI_API_KEY"] 获取 API 密钥 — 不得硬编码
  3. scrape() 函数应包含指数退避重试（5 次尝试）
  4. 按照下方错误表处理状态码
  5. 在发出任何请求前，将积分估算值输出到 stderr
  6. 使用 Site Profile 中确定的模式进行分页；同步模式的速率限制为 1 req/sec
  7. extract() 函数应预先填入 Site Profile 中的选择器（如果未确定选择器，则添加 TODO）
  8. 将输出以 JSON 格式写入 stdout 或 --output 文件
Node.js 脚本结构

使用与上述相同的标志和行为。使用 node-fetch@2 + commander。如果已知用户现有的模块格式（ESM 或 CommonJS），则与之保持一致；否则默认使用 CommonJS。

始终在生成的脚本顶部包含
# Requirements: pip install requests  (Python)
# Requirements: npm install node-fetch@2 commander  (Node.js)
# Usage: SCRAPERAPI_API_KEY=your_key python scraper.py --url "https://example.com" --pages 5

积分成本参考

配置每次请求的积分
标准1
render=true~10
premium=true~10
ultra_premium=true~30
结构化端点1–10（因垂直领域而异）

执行前打印成本估算：# Estimated: 50 pages × 10 credits = ~500 credits

生成的脚本必须包含 --max-credits 标志；如果估算值超出预算，则中止执行。

错误处理

状态操作
200解析并返回
401中止 — API 密钥无效，不要重试
403使用 premium=true 重试；如果仍受阻，则尝试 ultra_premium=true
404跳过此 URL — 页面不存在
429指数退避并重试；对于大型批次，切换到异步模式
500/503指数退避，最多尝试 5 次

验证清单

提交脚本前：

  • 已在 Phase 2 生成 Site Profile，且每项架构决策均注明其依据
  • 从 $SCRAPERAPI_API_KEY 环境变量读取 API 密钥 — 未硬编码
  • 重试逻辑涵盖 429、500、503，并使用指数退避
  • 存在 --max-credits 限制，并在首次请求前强制执行
  • 在发出任何请求前，将积分估算值输出到 stderr
  • 如果使用结构化端点：垂直领域名称与速查表完全一致
  • 如果使用异步模式：脚本包含轮询循环或 webhook 处理，而不只是提交任务
  • ultra_premium 和 premium 不会同时设置
  • 脚本顶部包含设置说明注释
  • 使用 TODO 注释标明用户应添加解析逻辑的位置

参考资料

评论

支持 Markdown