scrapfly-sdk-typescript

Scrapfly TypeScript SDK

使用 scrapfly-sdk 包从 TypeScript/JavaScript 抓取网页，支持代理轮换、反机器人绕过（Unblocker）、JavaScript 渲染、截图和 AI 提取。可在 Node.js、Deno、Bun 和边缘运行时（Cloudflare Workers、AWS Lambda）上运行。

适用场景

• 从 TS/JS 代码库抓取网页（HTML、JSON、文本、Markdown）
• 绕过反机器人保护（Cloudflare、DataDome、PerimeterX、Kasada）
• 使用无头浏览器渲染 JavaScript 密集型网页
• 截取屏幕截图或提取结构化数据
• 并发抓取多个 URL

设置

npm install scrapfly-sdk
# Deno / JSR: import from 'jsr:@scrapfly/scrapfly-sdk'
export SCRAPFLY_API_KEY="your-api-key"

在 scrapfly.io 获取 API 密钥。

基本抓取

import { ScrapflyClient, ScrapeConfig } from 'scrapfly-sdk';

const client = new ScrapflyClient({ key: process.env.SCRAPFLY_API_KEY });

const result = await client.scrape(
    new ScrapeConfig({ url: 'https://web-scraping.dev/products' }),
);

console.log(result.result.content);

反机器人绕过、地理定位、JS 渲染

ScrapeConfig 使用 snake_case 选项键，与 API 保持一致。

const result = await client.scrape(
    new ScrapeConfig({
        url: 'https://web-scraping.dev/products',
        proxy_pool: 'unblocker',            // residential proxies + the Unblocker (anti-bot bypass)
        country: 'us',                      // proxy country (ISO 3166-1 alpha-2)
        render_js: true,                    // headless browser rendering
        wait_for_selector: 'div.product',   // requires render_js
        rendering_wait: 5000,               // ms, requires render_js
        format: 'markdown',                 // raw | clean_html | json | markdown | text
    }),
);

截图和提取

import { ScreenshotConfig, ExtractionConfig } from 'scrapfly-sdk';

const shot = await client.screenshot(
    new ScreenshotConfig({ url: 'https://web-scraping.dev/products' }),
);
// shot.image is the binary image data

const html = (await client.scrape(
    new ScrapeConfig({ url: 'https://web-scraping.dev/reviews' }),
)).result.content;

const data = await client.extract(
    new ExtractionConfig({
        body: html,
        content_type: 'text/html',
        extraction_prompt: 'extract the reviews as JSON with fields: review, date, rating, author',
    }),
);
console.log(data.data);

并发抓取

const configs = [
    new ScrapeConfig({ url: 'https://web-scraping.dev/products?page=1' }),
    new ScrapeConfig({ url: 'https://web-scraping.dev/products?page=2' }),
];

for await (const result of client.concurrentScrape(configs)) {
    console.log(result.result.content.slice(0, 100));
}

重要说明

• render_js: true 是使用 rendering_wait、wait_for_selector 和截图的必要条件
• proxy_pool 用于选择代理池：'basic'（数据中心代理，不启用 Unblocker）、'unblocker'（住宅代理和 Unblocker）、'unblocker_ultra'（与前者相同，且是目标网站或具有独立价格的反机器人保护所接受的唯一代理池），或 'auto'（API 根据目标网站的配置，在请求前选择代理池：在数据中心代理上启用 Unblocker，或选择目标网站需要的代理池；所有目标网站均接受此选项，包括需要 unblocker_ultra 的目标网站，此时会另行计费；按实际使用的代理池计价）。每个代理池都会自行设置 Unblocker。对于具有独立价格的目标网站或反机器人保护，使用 basic 和 unblocker 会返回 ERR::PROXY::UNBLOCKER_ULTRA_REQUIRED（HTTP 422，不计费）：请使用 proxy_pool: 'unblocker_ultra' 重新发送请求。0.12.0 之后的版本中，ScreenshotConfig 使用相同的 proxy_pool
• unblocker: true 及其别名 asp 已弃用：请使用 proxy_pool（Unblocker 对应 'unblocker_ultra'）。迁移指南涵盖了代理池推出前编写的请求，包括代理池名称 'public_datacenter_pool' 和 'public_residential_pool'。如果显式提供 asp，则以 asp 为准
• 使用 format: 'markdown' 获取整洁、适合大模型使用的内容
• API 密钥从构造函数选项 key 中读取（传入 process.env.SCRAPFLY_API_KEY）
• 通过 result.result.content 读取页面正文